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

One runtime runs per user, as the login service kadmo service install sets up. Every MCP client's kadmo mcp relays to it and starts nothing itself, and the Kadmo extension connects to it on ws://localhost:9876/ws; that port cannot be changed. So when no runtime runs, no client has its tools, and when another program holds port 9876, no client has the browser.

Two commands show where it stands:

kadmo service status     # the login service, and whether it runs the runtime
kadmo doctor             # the runtime, the service, the port, the extension, the sessions

Runtime and CLI

Every call answers "The Kadmo runtime is not running"

Every tool call your MCP client makes answers with a message that starts:

The Kadmo runtime is not running: `kadmo mcp` relays to it and starts nothing itself.

and goes on with the command that starts it.

Cause: no runtime runs for your user, so the client's kadmo mcp has nothing to relay to. It keeps trying every 3 seconds.

Fix: run kadmo service status.

• No service is installed: run kadmo service install (Install the runtime).
• The service is installed but stopped: start it with your system's command, which the message names too (the table on Install the runtime), and read its logs there if it stops again.
• On Linux, the service cannot reach your user's systemd: it needs a desktop login session. On a machine without one, run loginctl enable-linger $USER, then kadmo service install.
• After a Node.js upgrade that moved the node binary, the service cannot start the runtime; kadmo service status says so. Run kadmo service install again.

Once the runtime answers, the client lists the tools again by itself; you do not restart it.

kadmo serve exits with "Another Kadmo runtime already runs for this user"

  Another Kadmo runtime already runs for this user: pid 2210, <version>, since 2026-10-17T10:15:02Z (/home/you/.kadmo/run/kadmo.sock).

Cause: the runtime runs once per user, and one already runs: usually the login service, or a kadmo serve in another terminal.

Fix: use the one that runs; there is nothing to start. kadmo service status says whether it is the service's. To run kadmo serve by hand instead, remove the service first with kadmo service uninstall.

kadmo service install stops at a runtime started by hand

Cause: a runtime you started yourself (kadmo serve in a terminal) runs for your user, and the service's runtime cannot run beside it. The command names its pid.

Fix: stop it (Ctrl+C in its terminal, or kill <PID>) and run kadmo service install again, or run kadmo service install --replace, which stops it first.

kadmo service install refuses to run from npx

Cause: npx runs the package from a cache that can be cleaned at any time, and the service would start a path that goes away.

Fix: npm install -g @kadmo/cli, then kadmo service install.

The service's runtime does not see a variable

Cause: the login service starts the runtime in ~/.kadmo, without your shell's profile, so it reads ~/.kadmo/.env, not the .env of a project folder or a variable you export in a terminal. It keeps the PATH of the shell you installed it from.

Fix: put the variable in ~/.kadmo/.env and run kadmo service restart. When a command the runtime calls (claude, node, npm) moved to another folder, run kadmo service install again from a shell that finds it.

"The browser cannot connect: 127.0.0.1:9876 is held by" another program

Every browser tool answers:

The browser cannot connect: 127.0.0.1:9876 is held by <program> (pid <PID>), not by the Kadmo runtime.

Cause: another program listens on port 9876, so the extension reaches it instead of the runtime. The runtime keeps serving your clients, names the program in every status, and tries the port again every 10 seconds.

Fix: stop that program; the runtime takes the port within 10 seconds. kadmo doctor names it, and so do:

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

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 the runtime 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 is the runtime's; browser_connected tells you whether the extension is attached.

kadmo run prints "The Kadmo runtime is not running."

  Running: My workflow

  The Kadmo runtime is not running.

The next line names the command that starts the runtime.

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 the runtime: kadmo service status says whether the login service is installed and running (see Every call answers "The Kadmo runtime is not running"). For a runtime you started on another port, pass -p with that port.

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 runtime's environment: ~/.kadmo/.env for the login service (then kadmo service restart), or the terminal of a kadmo serve you started. The env block of an MCP client's server entry reaches only its kadmo mcp, not the runtime. Then run the workflow again. See LLM steps.

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 the runtime running?	curl -s http://localhost:9876/health must answer. kadmo service status says whether the login service runs it; start it as above. 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
The runtime, under the login service	Linux: journalctl --user -u kadmo. macOS and Windows: ~/.kadmo/logs/service.log. kadmo service status names the place.
A kadmo serve you started	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 (while the runtime 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].