# Troubleshooting (/docs/troubleshooting)

Run turno doctor, then find the row it flags: one page per finding, with its fix.

This page is for when something does not work: run `turno doctor`, find the row it flags, and open its page here.

```sh
turno doctor                  # every check, with the fix under each problem
turno doctor --fix            # run every repair that is safe to run, then check again
turno doctor --security       # file modes, the port owner, literal secrets, unpinned servers, token age, the audit log
turno doctor --summary        # one line, for hooks and status lines
turno doctor --report         # a Markdown block for an issue: versions, agents, paths, mcpd, findings
turno browser doctor          # Chrome and every browser identity (needs turno-browser)
```

It exits with code 1 when a check fails; warnings exit 0. Each row below is one finding, with what doctor prints for it.

<FindingFilter>
## turno doctor [#turno-doctor]

| Finding | What doctor prints | Level |
| --- | --- | --- |
| [Node.js is too old](/docs/troubleshooting/node-too-old) | `node <node>, and turno needs 20 or newer` | failure |
| [An agent that profiles use is not installed](/docs/troubleshooting/agent-not-on-path) | `<command> not found on PATH, and profiles use it` | failure |
| [The launcher folder is not on your PATH](/docs/troubleshooting/launchers-not-on-path) | `<bin> is not on your PATH, so launchers like <launcher name> will not be found (turno <names> works meanwhile)` | warning |
| [Google Chrome is not installed](/docs/troubleshooting/chrome-not-found) | `Google Chrome not found: claude.ai links open in the default browser` | warning |
| [The launchers were written by another turno version](/docs/troubleshooting/upgrade-not-finished) | `turno <version> runs, but <recorded> set up the launchers` | warning |
| [A service account has no read_tools](/docs/troubleshooting/accounts-without-read-tools) | `accounts without read_tools: <no reads>; delegated reads get every tool of the account and ask like writes` | warning |
| [An agent's default or fallback names a profile of another agent](/docs/troubleshooting/agent-default-wrong-agent) | `agents.<id>.<role> = "<name>", but <name> is a <label> profile` | warning |
| [default or fallback names a profile that is not Claude Code](/docs/troubleshooting/default-wrong-agent) | `<role> = "<name>" is for <label>, but <name> is a <label> profile` | warning |
| [A folder rule uses a profile that does not exist](/docs/troubleshooting/rule-profile-missing) | `the rule for <path> uses profile <profile>, which does not exist` | warning |
| [A profile has no launcher](/docs/troubleshooting/profile-no-launcher) | `profile <name>: no launcher <launcher>` | failure |
| [A file with the launcher's name was not written by turno](/docs/troubleshooting/profile-launcher-not-ours) | `profile <name>: <launcher> was not generated by turno` | failure |
| [A launcher is out of date](/docs/troubleshooting/profile-launcher-stale) | `profile <name>: <stale>` | warning |
| [A profile's folder does not exist](/docs/troubleshooting/profile-folder-missing) | `profile <name>: <dir> does not exist` | failure |
| [A shared item is a local copy in one profile](/docs/troubleshooting/profile-local-copy) | `profile <name>: <item> is a local copy, not shared` | warning |
| [A profile is missing the link to a shared item](/docs/troubleshooting/profile-missing-link) | `profile <name>: missing link for <item>` | warning |
| [An agent-specific profile warning](/docs/troubleshooting/profile-agent-warning) | `profile <name>: <w>` | warning |
| [mcp.toml reads a variable that is not set](/docs/troubleshooting/mcp-env-not-set) | `<name> reads <list> from mcpd's environment, and <it is\|they are> not set here` | warning |
| [A server runs outside the gateway](/docs/troubleshooting/server-outside-mcpd) | `<name> runs outside mcpd` | warning |
| [A remote server needs a login](/docs/troubleshooting/oauth-login-required) | `<server><@<variant>> OAuth: <text>` | warning |
| [The gateway's service file has no program](/docs/troubleshooting/service-no-program) | `mcpd: <shown> has no program to run` | failure |
| [The gateway's service file runs a program that is gone](/docs/troubleshooting/service-program-missing) | `mcpd: <shown> runs <missing>, which no longer exists` | failure |
| [The gateway's service file runs a versioned path](/docs/troubleshooting/service-versioned-path) | `mcpd: <shown> runs a versioned path (<program>) that breaks when that version is removed` | warning |
| [The LaunchAgent runs as a Background process](/docs/troubleshooting/service-background-process) | `mcpd: the LaunchAgent runs as a Background process, which macOS throttles` | warning |
| [A gateway file belongs to another user](/docs/troubleshooting/token-file-foreign-owner) | `mcpd: <file> belongs to uid <uid>` | failure |
| [A gateway token file is readable by others](/docs/troubleshooting/token-file-readable) | `mcpd: <file> is readable by others (mode <st>)` | warning |
| [The gateway port answers with your token but belongs to another user](/docs/troubleshooting/port-foreign-mcpd) | `mcpd: port <port> answers with your token but belongs to uid <uid>` | failure |
| [The process on the port is not the mcpd that answers](/docs/troubleshooting/port-pid-mismatch) | `mcpd: port <port> is held by pid <pid>, but mcpd reports pid <pid>` | warning |
| [mcp.toml is invalid, and mcpd serves the last good copy](/docs/troubleshooting/mcp-toml-invalid) | `mcpd: mcp.toml is invalid, serving the <source>: <error>` | warning |
| [config.toml is invalid, and mcpd uses defaults](/docs/troubleshooting/config-toml-invalid) | `mcpd: config.toml is invalid, mcpd uses defaults: <error>` | warning |
| [Another process holds the gateway's port](/docs/troubleshooting/port-in-use) | `mcpd: port <port> is in use by <describe owner>, so mcpd cannot listen there` | failure |
| [The gateway's last start failed](/docs/troubleshooting/last-start-failed) | `mcpd: last start failed at <at>: <message>` | warning |
| [Synced configs point at another port](/docs/troubleshooting/configs-wrong-port) | `mcpd: <off> synced config<s> point at port <seen> but mcpd uses <port> (<off>)` | warning |
| [Synced configs still send the master token](/docs/troubleshooting/configs-master-token) | `mcpd: <legacy> synced config<s> still send<s> the master token, which mcpd no longer accepts for MCP sessions (<legacy>)` | warning |
| [Profile tokens are older than the gateway token](/docs/troubleshooting/profile-tokens-stale) | `mcpd: <stale> profile token<s> predate<s> the current gateway token (<stale>)` | warning |
| [The gateway's service file cannot be read](/docs/troubleshooting/service-file-unreadable) | `mcpd: cannot read the service file: <message>` | warning |

## turno doctor --security [#turno-doctor---security]

| Finding | What doctor prints | Level |
| --- | --- | --- |
| [No secret store was found](/docs/troubleshooting/no-secret-store) | `secret store: none found (no security or secret-tool on PATH)<; mcp.toml has keychain: references that cannot resolve>` | failure |
| [Other users can read or change turno's files](/docs/troubleshooting/permissions-wide) | `permissions: <wide> item<s> under turno's folders <can be changed\|can be read> by other users: <writable>` | warning or failure |
| [Files under turno's folders belong to another user](/docs/troubleshooting/permissions-foreign-owner) | `permissions: <foreign> item<s> under turno's folders belong to another user (a sudo run?): <foreign>` | warning |
| [Another user holds the gateway's port](/docs/troubleshooting/port-held-by-other-user) | `mcpd port <port>: held by <describe owner>, another user, so sessions would send it the gateway token` | failure |
| [A process that is not mcpd holds the gateway's port](/docs/troubleshooting/port-held-by-other-process) | `mcpd port <port>: held by <describe owner>, which does not answer as mcpd, so sessions would send it the gateway token` | warning |
| [mcp.toml holds literal secrets](/docs/troubleshooting/literal-secrets-mcp-toml) | `literal secrets in <mcp file>: <in manifest>` | warning |
| [An agent config holds literal secrets](/docs/troubleshooting/literal-secrets-agent-config) | `literal secrets in <file>: <found>` | warning |
| [Backups hold configs with literal secrets](/docs/troubleshooting/backups-hold-secrets) | `<holding> backup<s> in <dir> hold configs with literal secrets (oldest <holding>); backups are pruned after 30 days` | warning |
| [An MCP server runs whatever version is newest](/docs/troubleshooting/servers-unpinned) | `MCP servers without an exact version: <loose>` | warning |
| [The gateway token is old](/docs/troubleshooting/token-old) | `the mcpd token is <days> days old (more than <token_max_age_days>)<derived>` | warning |
| [Profile token files are older than the gateway token](/docs/troubleshooting/token-files-predate) | `<stale> profile token file< predates\|s predate> the mcpd token, so <its agent\|their agents> cannot reach mcpd (<stale>)` | warning |
| [The audit log cannot be read](/docs/troubleshooting/audit-log-unreadable) | `audit log: cannot read it: <message>` | warning |
| [The audit log's hash chain is broken](/docs/troubleshooting/audit-log-chain-broken) | `audit log: line <line>: <reason>` | failure |

## turno browser doctor [#turno-browser-doctor]

| Finding | What doctor prints | Level |
| --- | --- | --- |
| [A headed Chrome cannot open in an SSH session](/docs/troubleshooting/browser-ssh-session) | `this is an SSH session: a headed Chrome opens only in the signed-in desktop session (where mcpd runs)` | warning |
| [There is no display for a headed Chrome](/docs/troubleshooting/browser-no-display) | `no display: a headed Chrome cannot open here` | warning |
| [An identity's identity.json is invalid](/docs/troubleshooting/browser-identity-json-invalid) | `identity.json <problems>` | failure |
| [A Chrome was left running with no server](/docs/troubleshooting/browser-orphan-chrome) | `Chrome pid <pid> was left running on this profile with no server` | warning |
| [A Chrome that turno did not start holds the profile](/docs/troubleshooting/browser-foreign-chrome) | `Chrome pid <pid> holds this profile, but no turno process does` | warning |
| [An identity has a stale runtime lock](/docs/troubleshooting/browser-stale-lock) | `stale runtime lock of pid <node pid> (that process is gone)` | warning |
| [An identity is not signed in (NEEDS_AUTH)](/docs/troubleshooting/browser-needs-auth) | `NEEDS_AUTH: not signed in at <url>: <health> (checked <checked at>)` | failure |
| [An identity's health check could not run](/docs/troubleshooting/browser-health-check-failed) | `the health check of <url> could not run: <health> (checked <checked at>)` | warning |
| [An identity met challenges in the last 7 days](/docs/troubleshooting/browser-challenges) | `<recent> challenge<s> in the last 7 days on <sites> site<s> (<kinds>)` | warning |
| [Google Chrome is not installed (turno-browser)](/docs/troubleshooting/browser-chrome-not-found) | `Google Chrome not found` | failure |
| [The test launch of Chrome failed](/docs/troubleshooting/browser-smoke-launch-failed) | `smoke launch failed: <first line>` | failure |
</FindingFilter>

## What a run looks like [#what-a-run-looks-like]

`turno doctor` checks the system, your config files, every profile, the MCP servers, the look and the gateway. Under each problem it prints the command that fixes it (`fix:`) or the manual step (`manual:`). This is a run in a fresh HOME, before any setup (`-` rows are skipped checks, with an optional next step):

```text title="turno doctor"
System
  ok node 26.13.0
  -  claude not installed
     optional: install it: https://docs.claude.com/claude-code
  -  codex not installed
     optional: npm install --global @openai/codex
  ok secret store: macOS Keychain (security)
  ok Google Chrome installed
  ok turno 0.2.0

Config
  -  no ~/.config/turno/config.toml (defaults)
  -  no ~/.config/turno/mcp.toml yet
     optional: turno mcp import

Profiles
  -  no profiles yet
     optional: turno profile add <name>

Look
  -  status line: none in ~/.claude/settings.json
  -  font: MesloLGS Nerd Font 0/4 files in ~/Library/Fonts
     optional: turno ui install

Gateway
  -  mcpd: no token at ~/.local/state/turno/mcpd.token, so it has not started yet
     optional: turno mcp daemon start

4 ok, 8 skipped in 33ms
```

## When doctor finds nothing [#when-doctor-finds-nothing]

```sh
turno mcp daemon status       # running servers, clients, memory; or why mcpd is down
turno mcp daemon logs -n 100  # the gateway log, in local time
turno mcp log --server <name> # its recent tool calls, with errors and durations
turno mcp refresh <name>      # forget a cached tool list; a running mcpd relearns it
turno mcp call <name> [tool]  # list a server's tools, or call one, as a profile's session would
turno run <profile> --no-gateway  # the same account without the gateway or the status line
```

If a problem goes away with `--no-gateway` (or `TURNO_SAFE=1`), it comes from turno's gateway or status line; if it stays, from the agent or its account.

Each server also has its own stderr log under `~/.local/state/turno/logs/`. If you are still stuck, ask in [Discussions](https://github.com/wimo-dev/turno/discussions) or open an [issue](https://github.com/wimo-dev/turno/issues) with the output of `turno doctor --report`, which holds no tokens or secret values.