Early access: Ailimu is free while we build to 1.0. We'd love your feedback. Send feedback Get notified at 1.0
Ailimu

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.

"No server called … could be found", or "Nothing is listening at …"

Ailimu could not reach FileMaker Server at the Host you typed. For "no server called", check the address for a typo. For "nothing is listening", check the port and that FileMaker Server is running, and that the Data API and OData are switched on in its Admin Console.

When Ailimu runs in Docker, localhost means the container itself. Use the server's own address, or host.docker.internal for FileMaker on the same machine.

"… does not speak https", or "… is expecting https://"

The address and the server disagree about encryption. FileMaker Server normally needs an address that starts with https://. If it says the server does not speak https, the server is plain http or the port is not FileMaker's: change the scheme or the port to match.

"… certificate could not be checked"

FileMaker Server's certificate is self-signed, or comes from an authority Ailimu does not know. The best fix is a certificate from a recognised authority on FileMaker Server. Otherwise give Ailimu the authority's file: add it to the container and name it in docker-compose.yml, then restart.

services:
  ailimu:
    environment:
      NODE_EXTRA_CA_CERTS: /certs/ca.pem
    volumes:
      - ./ca.pem:/certs/ca.pem:ro

"Certificate has expired" means renew it on FileMaker Server. "Made out for a different name" means use the name on the certificate as the Host.

"… does not offer that service (501)"

FileMaker Server understood the address but does not provide what Ailimu asked for, and asking again will not change that. (If the message names a database and says it does not recognise it, that is a mistyped name: see the entry below.) The usual cause is that the Data API or OData is switched off: in FileMaker Server's Admin Console, open Connectors and turn on the one your connection uses. It can also mean this FileMaker Server is too old to have that API, or that the Host points at something that is not FileMaker, such as a proxy or a web page. Check the address, and that it starts with https://.

"… does not recognise the database …", or "… has no database called …"

FileMaker Server answered, but not for that file. A mistyped name is by far the usual cause, and FileMaker often answers it with a 501 "not implemented", which looks like a fault but is not one. When Ailimu can, it adds the files the account can see on that server and suggests the closest name, for example Did you mean "LEO"?

Check the Database name for an exact match. If it is right, check that the file is open on FileMaker Server, that the Data API and OData are enabled, and that the account's privilege set includes the extended privilege for the API in use. On the Connect step, Database offers a list of the files the account can see.

"Only an owner can connect to … for the first time"

The FileMaker account for this connection has never been used with that server address. Ailimu only sends a FileMaker login to a server it already goes to: the server of a published connection using the same account, or FM_HOST. Anything else needs an owner, so an editor cannot send a connection's password to a server of their choosing. Ask an owner to test and publish the connection once. After that, editors can work on it as usual.

The address itself must be just the server, like https://fm.example.com, with nothing after it.

A second server says 401, or the wrong user is being used

Every connection uses the default FM_USER and FM_PASS unless it has a pair of its own. If your second file is on another server, or needs another account, the default account will not work there. The Connect step shows which account the connection is using and the two variable names to add, such as FM_USER_SERVER6 and FM_PASS_SERVER6. Put them in .env, then restart the container. A name with a typo in it is ignored, and the connection quietly falls back to the default account, so check the spelling against the Connect step.

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

"PostgreSQL credentials are not set"

A PostgreSQL connection reads its own login, not the FileMaker one. Add PG_USER and PG_PASSWORD to .env (or PG_USER_<SLUG> and PG_PASSWORD_<SLUG> for one connection) and restart. The message names the exact variables.

PostgreSQL says the server does not accept encrypted connections

The connection asks for encryption by default. If the server has no TLS, set Encryption to Off on the Connect step, but only when the database is on the same machine or a network you trust. Otherwise turn TLS on in PostgreSQL.

"No tables found in schema" on a PostgreSQL connection

The connection works, but the Schema you entered holds no tables, or the Database is the wrong one. The message lists the schemas that do have tables in this database, with how many, and suggests the nearest spelling. Set Schema to one of them. If it says the account can see no tables anywhere, check the Database name, then make sure the account has USAGE on the schema and SELECT on its tables.

PostgreSQL connects from my machine but not from Ailimu

When Ailimu runs in Docker, localhost means the container. Use host.docker.internal for a database on the same machine, and see Using a PostgreSQL database for Linux. Also check that the server's pg_hba.conf allows the address the container connects from.

"permission denied" when Claude changes a record or runs a function

The account is not allowed to. PostgreSQL decides, whatever the wizard says. Grant UPDATE on the specific columns, or EXECUTE on the specific function, to the account in PG_USER.

A PostgreSQL search stops after 30 seconds

PostgreSQL ended a statement that ran too long. Narrow the search with a filter on an indexed column, or raise PG_TIMEOUT_SECONDS.

Every search fails with "syntax error in URL" (code -1002)

FileMaker's OData parser rejects a field name that is not plain letters, digits and underscores, or that is one of its own words, such as ID, Type or any name with a space. Ailimu quotes every field name from version 0.7.3, so update first (docker compose pull && docker compose up -d).

If it still happens, check the table's entity set name. A name with a ~ inside it (for example Org~B) cannot be read by FileMaker in any form. Press Read schema again on the profile card (the circular arrows): Ailimu now keeps the plainer copy of a table when there is one. If a table only exists under such a name, leave it unticked.

A search says "Showing 100 of 5,158 matching records"

That is the answer being cut to one page, not a limit on what Claude can ask. Claude can ask for the next page with skip, or narrow the search. Counting rows on a page gives the wrong total: the figure after "of" is FileMaker's own count.

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 Data step says how old it is. Press Read schema again, or the same button 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.

I cannot sign in to the wizard

Five wrong passwords for one email lock it out for fifteen minutes. Ask an owner for a reset link instead of retrying. If you are the only owner and have lost your password, see If the only owner is locked out.

The wizard asks for a setup code

That is first run: no account exists yet. The code is printed in docker compose logs when the connector starts, and is the same as ADMIN_TOKEN.

The backup will not open

Restoring says one of these:

A backup that is refused changes nothing on the server.

Claude is refused with "Unauthorized"

Claude has the wrong token for the address it uses. Each connection has its own token, shown on its Connect Claude step in the wizard, and it only opens that connection. Two things look like tokens and are not the one Claude needs:

Copy the connection's token from its Connect Claude step, or download the Claude Desktop extension again, which has the right one inside. A connection that was deleted and created again has a new token.

Claude Desktop shows Ailimu as not connected

Check how it was added:

Claude Desktop keeps a log for each MCP server. On a Mac it is in ~/Library/Logs/Claude/, in files named mcp-server-<name>.log. On Windows it is in %APPDATA%\Claude\logs\.

Claude Desktop reports a JSON error

claude_desktop_config.json is not valid JSON, and Claude Desktop ignores all of it. The usual cause is pasting a whole { "mcpServers": ... } block into a file that already had one. The file must contain a single "mcpServers" section, with a comma between entries and none after the last. Open **Settings

Developer > Edit Config**, fix the file, then quit and reopen Claude Desktop. The extension avoids this file entirely.

Claude Desktop says spawn npx ENOENT

Only for the by-hand mcp-remote setup: Claude Desktop cannot find Node.js. Install it from nodejs.org, then quit and reopen Claude Desktop. If Node.js was installed with a version manager, Claude Desktop may not see it: put the full path from which npx in "command" instead of npx. The extension does not need Node.js.

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

Open Activity in the wizard; editors and owners can see it. It lists every change Claude made and every script it ran, on every connection, newest first, and every admin action with who did it. Search by date, by a keyword such as a record ID or a value, by connection, and by Claude or people. Click an entry for its full details, or Download CSV for the current search.

Claude's reads are only there for connections where Record reads is on, because they can use a lot of disk. Failed calls are marked in red with FileMaker's error.

The same entries are plain text on the config volume, one file per day, if you would rather search them on the server:

docker compose exec ailimu sh -c 'grep -h INV-70114 /config/activity/*.jsonl'