Troubleshooting

What the common failures mean, and what to do about each one.

"FileMaker credentials are not set"

FM_USER and FM_PASS are missing from the container's environment. Add them to .env and recreate:

docker compose up -d --force-recreate

With several profiles, the banner names the exact variables: a profile can have its own FM_USER_<SLUG> pair. See the reference.

Test connection fails with 401

The account or password is wrong, or the privilege set is missing the extended privilege for the API you chose: fmodata for tables, fmrest for scripts and layouts. A file can have one enabled and not the other, so switching Read data through may get you past it.

The table list is full of <No Access>

You are reading through layouts with the Data API. That is the API telling you the account cannot reach those fields through that layout. Either fix the privilege set, or switch to OData, which reads the tables themselves.

A script I know exists is not listed

Almost always because it lives in a different file. FileMaker solutions are commonly split into a data file and an interface file, with the business scripts in the latter, and the Data API only lists scripts in the file you connect to.

Set Run scripts from on the Connect step to the other file. See the wizard.

If it is genuinely in this file and still missing, check that the account's privilege set can see it.

A script is listed but cannot be ticked

Two scripts in the file share that name. FileMaker's script= parameter takes a bare name and cannot be told which one you mean, so exposing it would run whichever FileMaker resolves first. Rename one of them in FileMaker.

The script tool fails when Claude calls it

• Wrong layout context. The layout decides what table and found set the script sees. If scripts come from a second file, the layout must be one of that file's.
• A PSOS_ or SVR_ script. Perform Script On Server behaves differently and some cannot run through the Data API at all.
• Read-only is on. Then no script tool exists at all, whatever is ticked.

Discovery is slow

Expect roughly seven seconds on a large file: schema, row counts, script and layout lists. It does not read any rows: sampling happens later, per table, when you open one.

If it is much slower, the row counts are usually the cost, and the file is large or the server busy. Opening a profile afterwards uses the cached schema and takes about a tenth of a second.

A table I added in FileMaker is not there

The schema is cached per profile, so Open shows what was last read. The Tables step says how old it is. Press Re-read schema, or Re-discover on the profile card. Your ticks are matched back on by name, so nothing is lost.

Claude does not see my new tools

A client reads the tool list once, when it connects. Publishing takes effect on the server immediately but an open session keeps the old list. Start a new session. You do not need to re-run claude mcp add.

Claude cannot reach the server

localhost only works if Claude runs on the same machine. Use the LAN address or hostname, and check the port is open.

I need to see what the agent actually did

Every write and every script call is logged to /config/audit.log on the config volume, whatever the audit settings say. Reads are only logged if you turn that on.

docker compose exec ailimu tail -f /config/audit.log

Each line records the time, the tool, the profile and the record it touched.