Troubleshooting

Symptoms you may see with the Kadmo runtime and the Kadmo extension on your own computer, why they happen, and how to fix them. Each heading is the symptom, quoted as the runtime or the extension prints it where there is a fixed message.

The one rule behind most problems

The Kadmo extension always connects to ws://localhost:9876/ws; its port cannot be changed. Only one process can listen on port 9876, so only one runtime process holds the extension at a time: either kadmo serve or one kadmo mcp started by your MCP client. Any other runtime on the computer has no browser.

To see which process holds the port:

lsof -nP -iTCP:9876 -sTCP:LISTEN     # macOS and Linux
ss -ltnp 'sport = :9876'             # Linux
ps -p <PID> -o command=              # what that PID is

Runtime and CLI

kadmo serve exits with EADDRINUSE

Failed to start server: Error: listen EADDRINUSE: address already in use 127.0.0.1:9876

Cause: another process already listens on port 9876, usually an earlier kadmo serve, or a kadmo mcp that an MCP client started (see A kadmo mcp process stays behind).

Fix: find the process with the commands above. If it is a runtime you want to keep, use it instead of starting a second one. Otherwise stop it (Ctrl+C in its terminal, or kill <PID>) and start again. kadmo serve -p <port> starts on another port, but the extension does not follow it: browser tools stay disconnected on any port other than 9876.

kadmo mcp logs "could not start HTTP server" and every browser tool fails

The MCP client's server log (the stderr of kadmo mcp) shows:

[kadmo] starting in stdio mode
[kadmo] warning: could not start HTTP server: Error: listen EADDRINUSE: address already in use 127.0.0.1:9876
[kadmo] ready for MCP connections via stdio

and every browser tool (navigate, snapshot, click, ...) answers:

Browser not connected. Kadmo browser tools drive real Chrome through the Kadmo extension, which connects to this server on 127.0.0.1:9876. Install it from https://chromewebstore.google.com/detail/djmmpdellmdkdghbbignndjlfojojcmh, then click the Kadmo icon in Chrome. An extension on another machine cannot reach this server: the port stays on loopback; run `npx @kadmo/cli` on the machine whose Chrome you want to drive. Workflow, run-log, artifact and knowledge-pack tools need no browser.

Cause: kadmo serve or another runtime already holds port 9876, so it holds the extension. The new kadmo mcp keeps serving MCP over stdio, but without a browser. get_browser_status still reports Server Running: true in this state; look for the warning line instead.

Fix: keep one runtime. For an MCP client, stop kadmo serve and let the client start kadmo mcp on its own, then restart the client. Note that kadmo mcp serves no dashboard: while it holds the port, http://localhost:9876 shows nothing, and you read run logs with the list_run_logs and get_run_log tools or in ~/.kadmo/run_logs.

An MCP client configured with http://localhost:9876/mcp gets 401

The client reports HTTP 401 with the body {"error":"Unauthorized"}, or shows no Kadmo tools.

Cause: HTTP /mcp needs Authorization: Bearer $KADMO_AGENT_TOKEN on every request, even from the same computer. A desktop install has no such token, and kadmo serve warns about it at start: [kadmo] HTTP /mcp needs KADMO_AGENT_TOKEN; use kadmo mcp over stdio.

Fix: configure the client to start kadmo mcp over stdio. The recipes for each client are on MCP setup. The shape is:

{
  "mcpServers": {
    "kadmo-agent": { "command": "npx", "args": ["-y", "@kadmo/cli", "mcp"] }
  }
}

kadmo status says "Not running" while the runtime runs

Cause: kadmo status always asks http://localhost:9876/health; it has no -p option (kadmo status -p 9877 fails with error: unknown option '-p'). A runtime started on another port is reported as Server: Not running.

kadmo status also exits with code 0 whether or not a runtime answers, so a script cannot use its exit code. Check the printed Server: line, or call the port you use directly:

curl -s http://localhost:9877/health

/health answers on both kadmo serve and kadmo mcp; browser_connected tells you whether the extension is attached.

kadmo run prints "Server is not running."

  Running: My workflow

  Server is not running.

  Start the server first: kadmo serve

Cause: kadmo run does not run the workflow itself; it asks the runtime on http://localhost:9876 (or the port given with -p) to run it, and nothing answered there.

Fix: start kadmo serve in another terminal, or pass -p with the port of the runtime you started.

A runtime started by kadmo mcp passes the check, because the check only reads /health, but it has no run API: kadmo run then prints Status: undefined and Message: Route POST:/api/workflows/<id>/run not found, and exits 0. Use kadmo serve for kadmo run, or the MCP tool run_workflow from your client.

kadmo run prints "Status: started" and returns at once

  Running: My workflow

  Status: started

  Run ID: my_workflow_20261008T065001721_e48da5

Cause: kadmo run starts the run and returns without waiting; started is not a result, and the exit code is 0 even if the run fails a moment later.

Fix: read the outcome in the run log: in the dashboard at http://localhost:9876/run-logs/<run id>, in the file ~/.kadmo/run_logs/<run id>.json, or with the MCP tool get_run_log. See Dashboard.

If the workflow has browser steps and no extension is attached, kadmo run prints Status: undefined, starts no run and still exits 0. The runtime refused the run with Browser not connected; connect the extension and run it again.

kadmo run prints Workflow not found: <id>

kadmo run and kadmo list read workflows from ~/.kadmo/actions, ~/.kadmo/workflows and the installed packs. A fresh install has none. Run kadmo list to see the ids that exist, and install a pack or add a workflow file first (Workflows).

A workflow fails with "OpenAI API key not configured"

The run log ends with OpenAI API key not configured (or Anthropic API key not configured) at an llm.* step.

Cause: the step uses the LLM provider from the dashboard's Settings (OpenAI unless you changed it) and found no key there or in the environment of the runtime process.

Fix: enter the key in the dashboard under Settings → LLM Provider, or set OPENAI_API_KEY or ANTHROPIC_API_KEY in the environment that starts the runtime: the terminal of kadmo serve, or the env block of the MCP client's server entry for kadmo mcp. Then run the workflow again. See LLM steps.

A kadmo mcp process stays behind

After you quit the MCP client, lsof or ss still shows a node ... kadmo mcp process on port 9876, and the next kadmo mcp logs could not start HTTP server (see above).

Cause: kadmo mcp does not exit when its standard input closes. With the HTTP side bound to the port, the process keeps running and keeps the port until it gets a signal. Clients that stop their server process with a signal end it; a client that only closes the pipe, or one that crashes, leaves it behind.

Fix: find it with lsof -nP -iTCP:9876 -sTCP:LISTEN and stop it with kill <PID>, then restart the client.

kadmo serve --host 0.0.0.0 refuses to start

[kadmo] Refusing to start: binding 0.0.0.0 (non-loopback) without KADMO_AGENT_TOKEN would expose the API unauthenticated on the network.
  • Set KADMO_AGENT_TOKEN to enable a wide bind, or
  • bind loopback (omit --host / set KADMO_HOST=127.0.0.1).

Cause: a bind beyond loopback (--host or KADMO_HOST) needs a token. On your own computer, leave --host out; the default 127.0.0.1 is what the extension and the dashboard use.

A line about "CLAUDE.md tracker block" at every start

  CLAUDE.md tracker block: skipped (no canonical file at /Users/you/.kadmo/skills/agents/claude/CLAUDE.md)

This is information, not an error. The block comes with the agent ops, which a desktop install does not have, so the runtime skips it and changes nothing.

Packs

Message	Cause	Fix
Pack not found: <name>. Run 'kadmo search' to see available packs.	No added registry and no pack in the public catalogue at https://app.kadmo.ai has that domain.	Check the spelling with kadmo search <query>, or install from a path or git URL. See kadmo install.
— <domain> kept: <domain> is held by the override layer, which outranks account	One install per domain; a pack from a higher layer (override, then account, then agent ops, then library) already holds it, and a lower one never replaces it. Exit code 0.	kadmo install --list shows the layer. To replace it, kadmo uninstall <domain>, then install again.
— <domain> already installed (same version)	The same version is installed.	kadmo install <source> --force to reinstall.
Already installed (v1.0.0). Use --force to overwrite.	Another version of the pack is installed at the same layer.	Add --force.
The agent ops: no agent token: set KADMO_AGENT_TOKEN or AGENT_TOKEN (or put it in ~/.agent-env)	kadmo install agents fetches the agent ops from the Kadmo app with an agent's token. Desktop installs have none, and the agent ops are not meant for them.	Nothing to fix on a desktop: install packs by name, path or git URL instead.
Not logged in. Run `kadmo login` first.	kadmo publish found no ~/.kadmo/auth.json.	kadmo login --token <personal API token from the Kadmo app>. See kadmo login.
Logged in to <url>, but the app is now <url>. Run `kadmo login` for <url>.	The stored token belongs to another app address than the current one (KADMO_APP_URL or app_url in ~/.kadmo/settings.json).	Log in again for the current address, or set the address back.

Extension

The popup shows "Not Connected" / "Kadmo runtime not reachable"

The popup has three states: "Connecting..." while it attaches, "Connected" with a detail line, and "Not Connected" with the detail "Kadmo runtime not reachable". "Not Connected" means that no tab is attached; its detail line is fixed text and appears even when the runtime runs.

Check	Fix
Is a runtime holding port 9876?	curl -s http://localhost:9876/health must answer. Start kadmo serve, or start your MCP client so it starts kadmo mcp. The extension retries every 3 seconds on its own.
Was the runtime started on another port?	The extension only uses 9876. Restart the runtime without -p.
Is the active tab a restricted page (table below)?	Open a regular http:// or https:// page and click Connect. On a restricted page the button shows "Connection failed" for two seconds.

If the popup says "Connected" but the detail line reads "Kadmo runtime not reachable", a tab is attached but the runtime is not: start it, or see the next section.

Two Chrome profiles have the extension

The runtime accepts one extension connection. A second profile (or a second browser) is closed with code 4000 and the runtime logs [kadmo] Rejected extension connection — another instance is already connected. That extension waits 30 seconds before it tries again, so it takes over at most 30 seconds after the first profile disconnects. Its popup reads "Kadmo runtime not reachable" in the meantime.

Fix: keep the extension enabled in the one profile you want to automate, and disable it in the others.

Browser tools fail on certain pages

Chrome does not let extensions attach to or script these pages, and the extension refuses them before it tries:

URL starts with	What it is
chrome://, edge://	Browser settings and internal pages
chrome-extension://	Pages of extensions
devtools://	Developer tools
about:	about:blank and similar
view-source:	Page source views
chrome-search://	The New Tab page
chrome-untrusted://	Sandboxed browser content
chrome-distiller://	Reader mode
https://chromewebstore.google.com, https://chrome.google.com/webstore	The Chrome Web Store

On these pages the tools answer Cannot operate on restricted URL: <url>. Please navigate to a regular webpage first., and connecting answers Cannot connect to restricted URL: <url>. Navigate to a regular webpage first. Embed buttons do not appear there either.

Fix: go to a regular web page, for example with the navigate tool or a browser.navigate step.

Tools answer "Browser not connected." while the extension runs

The extension reaches the runtime, but no tab is attached: when the extension connected, every open tab was a restricted page. The runtime then answers every browser tool with the same Browser not connected. message as when no extension is connected at all; the popup shows Not Connected. It attaches to the next regular page that finishes loading; open one, or click Connect in the popup on a regular page.

Where the logs are

What	Where
kadmo serve	The terminal it runs in.
kadmo mcp	Its stderr, which the MCP client keeps in its own server log; stdout carries the MCP messages.
Workflow runs	~/.kadmo/run_logs/<run id>.json; the dashboard at http://localhost:9876/run-logs (only while kadmo serve runs); the MCP tools list_run_logs and get_run_log.
The extension	chrome://extensions → Kadmo → service worker: the console of its background service worker, with lines prefixed [Kadmo].