Components and Web Viewer connection problems

Web Viewer development uses a live connection to FileMaker Pro through its built-in Agent Access, not a plugin or a window you keep open. A file is reachable as soon as FileMaker Pro has it open, Agent Access is on, and the file's grant prompt has been answered.

Start with the agent

Diagnose the connection to my FileMaker file, fix what you can, and tell me what still needs my action.

Agent Access is not enabled

If the diagnosis reports "Agent Access does not appear to be enabled in FileMaker Pro," open File → Manage → Agents in that copy of FileMaker Pro and tick "Enable Agent Access for this application." ADT uses port 19080 by default. If FileMaker Pro shows a different port, set FM_DEV_SERVER_PORT to that value in your shell profile or coding agent host, then restart the terminal or host so ADT inherits it. This is a one-time setting — it stays on until someone turns it off — but it's easy to miss on a copy of FileMaker Pro that hasn't been set up for ADT yet.

If Manage Agents is not in the menu, see The Manage Agents Option Is Missing. That page covers the required developer preview build and how to find the ClarisConfig.json FileMaker Pro actually loads.

The grant prompt is waiting, or was declined

The first time ADT runs a script in a file after FileMaker Pro starts, FileMaker Pro shows a grant prompt. A command that seems to hang — typegen, deploy, an agent data tool, or a browser page under pnpm dev waiting on data — is often this prompt waiting behind another window; bring FileMaker Pro to the front and look for it. Quitting FileMaker Pro clears every grant, so the prompt comes back after a restart, and a grant revoked in File → Manage → Agents comes back the same way.

If the prompt was declined, the file is still recorded and filemaker schema work still runs, but live Web Viewer work needs the grant. Ask the agent to reconnect, which raises the prompt again:

Reconnect this agent session to my open FileMaker file and check the setup again.

More than one copy of FileMaker Pro is running

Agent Access is per copy of FileMaker Pro, and only one copy can hold a given port. If two copies need Agent Access at the same time, give them different ports and set FM_DEV_SERVER_PORT in each ADT environment to select the copy you want to reach. Keep the setting in your shell profile or coding agent host's environment configuration so it survives a single command. The port is deliberately not stored in adt.json: it describes this machine and copy of FileMaker Pro, not the project.

If the extra copy is accidental — for example, a FileMaker Pro window on another account or a leftover process from an earlier session — quit the copy that should not be answering ADT, then check the connection again. See System Requirements for the full environment setup.

FileMaker Pro is older than 26.1

Agent Access does not exist before FileMaker Pro 26.1. If the diagnosis reports Agent Access is unavailable, see The Manage Agents Option Is Missing to check the version and get the developer preview build.

The file is not open

ADT can only reach a file FileMaker Pro currently has open. If the diagnosis reports the file isn't open, open it in FileMaker Pro and ask the agent to check again.

Components are missing or outdated

The agent can inspect the custom functions, layouts, and scripts under the Agentic Development Toolkit folders without changing them. Ask it to show the proposed reconciliation, then approve the update if the report matches the installed ADT version.

See Check and update a file's ADT components for the full process.