Troubleshooting
Troubleshooting Aki MCP Server
The most common problems and how to fix them, each as symptom, cause, then fix. A connection problem is usually the public address or the sign-in, not a bug in your code.
A word you do not know? Words you will meet
Claude cannot connect while Funnel says “on”
The serve-config can save locally but fail to sync to Tailscale, so a real client is blocked at TLS while your own machine sees everything as fine.
- 1Do not test with a bare
curl https://your-hostfrom the machine running the server: it takes the internal mesh shortcut. - 2Test the real public path with
dig @8.8.8.8 your-host A +shortthencurl --resolve your-host:443:<IP> https://your-host/.well-known/oauth-authorization-server. - 3If it times out despite “on”, copy the Re-sync command from the panel’s Tailscale help and run it in a terminal (it needs
sudo) to force a config re-push. From 4.1 it ends in the port your server listens on, not always 9999.
“Wrong token” or panel 403 on a second launch
A second launch used to race the running instance for the same ports. The server now reuses the running panel when the version matches, or stops the older one first.
- Make sure you are on a current version. If a stale panel tab is open, reload it from the freshly launched instance.
Port already in use (EADDRINUSE)
- The gatekeeper uses a fixed port 9999; a genuine conflict now names the likely cause. Free the port or stop the other process.
- The panel falls back to the next free port automatically if something else holds 9998.
A client gets 429 after wrong credentials
5 rejected credentials in 60 seconds block a caller for 15 minutes. A valid Bearer token is never blocked, so a working connection is not affected.
- 1Wait 15 minutes, or open the panel’s “Security & connection limits” section and press Release next to the blocked caller.
- 2Check the passphrase you typed. Copy it from the panel (click the eye button to reveal).
- 3If you keep hitting the limit legitimately, raise the numbers in the panel’s “Security & connection limits” section.
A web AI cannot finish signing in
AkiMCP returns a sign-in only to an address it knows. A refused one answers invalid_redirect_uri with a line that says where to add the address, why it cannot be added, or that the AI sent none.
- 1Open the panel’s “Connectors” section → Web · needs ingress → Other AI (sign-in). If the AI’s address shows under Refused since AkiMCP started, click Add, then connect again and type the passphrase.
- 2An address shown with a reason instead of a button (http, localhost, an IP address) cannot be added: the AI has to sign in through a public https address.
- 3Nothing listed as refused? The AI never reached AkiMCP: check that the public address works (see Get started) and that the connector uses the MCP URL from the panel.
A command is refused
- The message says why and names the allowed subcommands. Add the command in the panel’s “Allowed shell commands” section if you trust it.
- Git write forms (
branch -D,tag -d,remote set-url,--output=) are refused on purpose. Run them yourself, or allow baregitknowing it then allows everything.
A tool is refused: missing or stale rule receipt
Every tool that can act needs the current rule receipt that aki__akidevrule_context returns. The refusal code says which case it is: RULE_RECEIPT_MISSING (none sent), INVALID (not sha256: plus 64 hex characters), UNKNOWN (not issued since this server started), EVICTED (dropped out of the 200 the server keeps), STALE (a rule file changed since) or UNCHECKED (the rules could not be read).
- 1The refusal carries its own fix:
call aki__akidevrule_context (without knownReceipt if the rules are no longer in your context), then call this tool again with receipt=<the sha256:… it returns>. Ask the AI to do exactly that. - 2After restarting akimcp or editing a rule file, older receipts turn
UNKNOWNorSTALE. A receipt that sat unused while 200 newer ones were issued or used turnsEVICTED; one a chat keeps using stays valid. Either way, fetch a fresh one. - 3A tool that acts on a project with a
CLAUDE.md,AGENTS.mdorGEMINI.mdmay first return that project’s rules and a new receipt instead of running. That is not an error: call it again with the new receipt. - 4If the tool has no
receiptargument at all, the chat holds an old schema: reconnect akimcp or start a new chat.
A call fails with -32602 (invalid arguments)
A chat keeps the tool schema it loaded. After an update it can send an argument the new schema no longer takes, and the protocol answers -32602. The error now says which case it is.
- 1If it reads
<tool> takes no <argument>; its arguments are …, the argument name is not one this version takes: use a name from the list it prints. - 2If it ends with
tool schema is stale; reconnect AkiMCP or start a new chat, every argument is valid for the running server but not for the schema your chat cached. Reconnect akimcp in the client, or start a new chat, then retry. - 3Updating from 2.2 to 3.x: reconnect akimcp in every client once, because tool definitions changed in 3.0.0 and Claude asks “Always allow” again for the tools that changed. Updating from 3.0.x to 3.1.0: restart, then reconnect once so the client sees the new session-file input. Updating to 4.1.0: reconnect once, and Claude asks “Always allow” again for every tool that takes a receipt and for six more. Updating to 4.2.0: reconnect once so the client sees the new sqlite_query description.
chrome_interact will not type, or chrome_stop answers stopped: false
Since 4.2 both tools say what really happened instead of answering success.
- 1
Element <div> is not a text field: typing needs an input or textarea: the selector points at a button, a select or a plain element. Pointtypeat theinputortextareaitself. - 2
stopped: falsewithits Chrome is already gone: that Chrome had already closed, so nothing was signalled and its session was cleared. Nothing else to do. - 3
stopped: falsewithcould not check whether its Chrome is still running: AkiMCP could not confirm the process is that Chrome, so it left it alone. Close the window yourself, or pass itspidtochrome_stopif you are sure.
chrome_launch fails with no_profile
Browser profiles live in ~/.aki/cdp/profiles/<browser>-<profile>/ and only the optional AIObox app creates them. chrome_launch opens or attaches to one and never creates or copies it. The error reads Profile "chrome-profile-14" not found in … AkiMCP opens existing shared profiles and does not create them. (no_profile; next: …).
- 1Use an id the error lists after
open one of, or pass the folder name such asProfile 14.chrome_profileslists the shared ids too. - 2No shared profile yet? Attach instead: find the port of a Chrome running with a remote-debugging port using
aki__port_status, runaki__devtools_targetson it, match the tab by title or url, then pass that port and targetId explicitly. - 3The old
~/.aki/mcpsv/chrome-clonesfolder is no longer read and can be deleted, and therefreshargument is gone.
chrome_launch answers aiobox_running
Since 4.1, while the AIObox app is running, chrome_launch opens and attaches nothing, so an AI cannot end up acting from a profile signed in to another account. The answer names one next step.
- 1Ask the AI to do what the answer says:
aki__aiobox_write op=open_url url=<link> profileId=<id>opens the link from the AIObox window instead. - 2There is no force flag. To launch a profile yourself, quit AIObox first; without AIObox, or with
aki__aioboxswitched off in the panel,chrome_launchworks as before. - 3AIObox is closed and the answer still comes? AkiMCP counts it as running only while the process recorded in
~/.aki/aiobox/cdp/windows.jsonis alive. In the rare case another program took over that process ID, open AIObox and open the link from its window.
A browser call ends with “code timeout” after 50 seconds
A client gives up on a tool call after about a minute and then shows nothing, so every CDP call (devtools_eval, devtools_screenshot, devtools_targets, tab requests, postman_eval) ends within 50 seconds, finding the target and connecting included. A frozen or hidden tab, a script that never returns, or an endpoint that does not answer reaches that bound.
- 1
the page did not answer within 50s (the tab is frozen, or the script is still running): the script may have run. Check with a short read-only expression before running it again. Still no answer means the tab is frozen, so reload or close it yourself. - 2
the page gave no screenshot within 50s (the tab is frozen or hidden): try once more. Still none means the tab is frozen or hidden: show or reload it. - 3
the CDP endpoint host:port did not answer within 50s: check the app is running withaki__port_status, then try once more. Since 3.0.1 this message also covers a call that timed out while still listing tabs or connecting: nothing ran, so there is no need to check for side effects. 3.0.0 could say “the script may have run” in that case.
A background task or Postman will not start
aki__task_start and the Launch Postman button in the panel fail with the system error code of the failed start, and the server keeps running. Before 3.0.1 a task that failed to start ended the whole server, and a failed Postman launch ended the Postman helper, so update if you see that.
- 1
Failed to spawn background task process: ENOENT: the working folder or the program does not exist. Check thecwdyou passed and that the program is installed and on the server’sPATH. - 2
Failed to spawn background task process: EACCES: the program exists but is not executable. Fix its permissions or point to the right binary. - 3
Failed to launch Postman: ENOENTorEACCES: install Postman, or fix the permissions of its binary, then press Launch Postman again. - 4A command refused before any start was tried is a different case: see “A command is refused” on this page.
A tool is missing, or a call says the tool is disabled
Tools of an app that is not installed are not served, and optional providers can be switched off. agy and Kiro CLI start off, because each hands a whole task to another paid agent. Rule context, files, search and shell are always on.
- 1Open the panel’s “Tool providers” section. A provider whose app is missing shows why:
agy is not on PATH,kiro-cli is not on PATH,Postman app not found,no Chromium browser installed (Chrome, Brave, Edge), or no~/.aki/aiobox/folder for the optional AIObox tools. - 2Install the app, then press Detect again. No restart is needed.
- 3For
agyand Kiro CLI, also switch the provider on in the same section. - 4A switch applies on the server at once, but a client sees it only on its next tool list: start a new chat or reconnect the connector. Until then a call to a hidden tool fails with an error that says the tool is
disabled.
ClickUp says “Connection request invalid”
ClickUp keeps the client ID it first registered with. When AkiMCP forgot that registration (Remove only, Revoke & roll, or a sign-in never approved within an hour), versions before 3.3.1 refused the old ID with no way forward.
- 1Update AkiMCP to 3.3.1 or later with the install command, then restart it.
- 2Connect again from ClickUp and type the passphrase. AkiMCP takes the old ID back and lists it in the panel’s “Security & connection limits” section as
MCP client.
After a rename, an app shows no tools or the old ones
A new Server ID or Tool prefix changes every tool name, and each app keeps the list it loaded.
- 1Restart AkiMCP after Save name.
- 2Reconnect it in each app. In Claude Code, Codex, Cursor and AGY, click Apply. For a web connector, type the new Display name as its name.
- 3In Claude, allow each tool again (Always allow), then start a new chat.
A secret may have leaked
Open the control panel and roll the secret that was exposed.
- Passphrase:
Roll passphrase, thenRoll & sign out all clients. - Access token:
Roll & sign out all clients, then reconnect each AI with the passphrase. - After a token roll: Cursor, Claude Code and Codex take the new token from Apply on their panel tab; Postman’s JSON (or the Any MCP app JSON) and Buda’s header are pasted again. Web AI apps signed in with the passphrase refresh on their own, except ClickUp, which you reconnect once. The Claude app and AGY use no token.
Gemini connects but does not use the tools
- This is a known limitation: the OAuth handshake succeeds but tool discovery is unreliable. Use Claude, Grok, or ChatGPT for real work today.