Errors and diagnostic messages

Use the structured error code and any FileMaker database error number when diagnosing a failure. Similar sentences can describe different causes.

Message or code	Meaning	Next step
No adt.json found in this directory or any parent.	The agent is outside an ADT project.	Open the correct project or create one.
No FileMaker file is connected to this project.	The project has no file entry.	Connect the file.
Multiple files connected, none selected	ADT cannot infer the target.	Tell the agent which connected file to use.
authentication_failed / FileMaker 212	FileMaker rejected the account or password.	Check FileMaker credentials.
permission_denied / FileMaker 207	The account authenticated but lacks schema access.	Use a Full Access account for native file structure work.
locked / FileMaker 303	Another FileMaker session holds the schema lock.	Close Manage Database, the graph, or the script editor, then retry.
credential_prompt_declined	The native credential window was cancelled or left incomplete.	Stop and ask the user whether to authorize another attempt.
keychain_denied	macOS denied access to an existing keychain item.	Grant access in Keychain Access. Saving the password again does not fix the denial.
run_timeout	The native operation exceeded its time limit.	Have the agent inspect the reported phase and read the file before retrying.
session_not_authorized	This coding-agent session is not authorized for the file.	Grant Agent Access to the file again.
ADT local service unavailable	FileMaker Pro is closed, the file isn't open, Agent Access is off, or ADT is checking the wrong port.	Open the file, enable Agent Access, and make sure FM_DEV_SERVER_PORT matches any non-default port — see Components and Web Viewer connection problems.
Components absent	The selected Web Viewer workflow needs ADT's file components.	Ask the agent to install the components.
METADATA_PREFLIGHT_FAILED	A record request names an unavailable layout.	Confirm the exact layout and account access.
UNKNOWN_FIELD_NAME	A record request names a field not exposed by the layout.	Inspect the layout metadata and use a placed field.
UNKNOWN_PORTAL_NAME	A record request names an unavailable portal object.	Inspect the layout and use the exact portal name.
FileMaker 401	A find returned no matching records.	Treat no match as data, or adjust the find.
FileMaker 106	A referenced table occurrence is missing.	Inspect the relationships graph and correct the occurrence name.

If a message is not listed, ask the coding agent to collect the complete error object and the diagnostic result for the same task and FileMaker file. Continue with Collect information for support if the remediation does not resolve it.