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.
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.
turno doctor
| Finding | What doctor prints | Level |
|---|---|---|
| Node.js is too old | node <node>, and turno needs 20 or newer | failure |
| An agent that profiles use is not installed | <command> not found on PATH, and profiles use it | failure |
| The launcher folder is not on your 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 | Google Chrome not found: claude.ai links open in the default browser | warning |
| The launchers were written by another turno version | turno <version> runs, but <recorded> set up the launchers | warning |
| A service account has no 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 | agents.<id>.<role> = "<name>", but <name> is a <label> profile | warning |
| default or fallback names a profile that is not Claude Code | <role> = "<name>" is for <label>, but <name> is a <label> profile | warning |
| A folder rule uses a profile that does not exist | the rule for <path> uses profile <profile>, which does not exist | warning |
| A profile has no launcher | profile <name>: no launcher <launcher> | failure |
| A file with the launcher's name was not written by turno | profile <name>: <launcher> was not generated by turno | failure |
| A launcher is out of date | profile <name>: <stale> | warning |
| A profile's folder does not exist | profile <name>: <dir> does not exist | failure |
| A shared item is a local copy in one profile | profile <name>: <item> is a local copy, not shared | warning |
| A profile is missing the link to a shared item | profile <name>: missing link for <item> | warning |
| An agent-specific profile warning | profile <name>: <w> | warning |
| mcp.toml reads a variable that is not set | <name> reads <list> from mcpd's environment, and <it is|they are> not set here | warning |
| A server runs outside the gateway | <name> runs outside mcpd | warning |
| A remote server needs a login | <server><@<variant>> OAuth: <text> | warning |
| The gateway's service file has no program | mcpd: <shown> has no program to run | failure |
| The gateway's service file runs a program that is gone | mcpd: <shown> runs <missing>, which no longer exists | failure |
| The gateway's service file runs a versioned path | mcpd: <shown> runs a versioned path (<program>) that breaks when that version is removed | warning |
| The LaunchAgent runs as a Background process | mcpd: the LaunchAgent runs as a Background process, which macOS throttles | warning |
| A gateway file belongs to another user | mcpd: <file> belongs to uid <uid> | failure |
| A gateway token file is readable by others | mcpd: <file> is readable by others (mode <st>) | warning |
| The gateway port answers with your token but belongs to another user | mcpd: port <port> answers with your token but belongs to uid <uid> | failure |
| The process on the port is not the mcpd that answers | 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 | mcpd: mcp.toml is invalid, serving the <source>: <error> | warning |
| config.toml is invalid, and mcpd uses defaults | mcpd: config.toml is invalid, mcpd uses defaults: <error> | warning |
| Another process holds the gateway's port | mcpd: port <port> is in use by <describe owner>, so mcpd cannot listen there | failure |
| The gateway's last start failed | mcpd: last start failed at <at>: <message> | warning |
| Synced configs point at another port | mcpd: <off> synced config<s> point at port <seen> but mcpd uses <port> (<off>) | warning |
| Synced configs still send the 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 | mcpd: <stale> profile token<s> predate<s> the current gateway token (<stale>) | warning |
| The gateway's service file cannot be read | mcpd: cannot read the service file: <message> | warning |
turno doctor --security
| Finding | What doctor prints | Level |
|---|---|---|
| No secret store was found | 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 | 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 | permissions: <foreign> item<s> under turno's folders belong to another user (a sudo run?): <foreign> | warning |
| Another user holds the gateway's port | 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 | 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 | literal secrets in <mcp file>: <in manifest> | warning |
| An agent config holds literal secrets | literal secrets in <file>: <found> | warning |
| Backups hold configs with literal 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 | MCP servers without an exact version: <loose> | warning |
| The gateway token is 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 | <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 | audit log: cannot read it: <message> | warning |
| The audit log's hash chain is broken | audit log: line <line>: <reason> | failure |
turno browser doctor
| Finding | What doctor prints | Level |
|---|---|---|
| A headed Chrome cannot open in an 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 | no display: a headed Chrome cannot open here | warning |
| An identity's identity.json is invalid | identity.json <problems> | failure |
| A Chrome was left running with no server | Chrome pid <pid> was left running on this profile with no server | warning |
| A Chrome that turno did not start holds the profile | Chrome pid <pid> holds this profile, but no turno process does | warning |
| An identity has a stale runtime lock | stale runtime lock of pid <node pid> (that process is gone) | warning |
| An identity is not signed in (NEEDS_AUTH) | NEEDS_AUTH: not signed in at <url>: <health> (checked <checked at>) | failure |
| An identity's health check could not run | the health check of <url> could not run: <health> (checked <checked at>) | warning |
| An identity met challenges in the last 7 days | <recent> challenge<s> in the last 7 days on <sites> site<s> (<kinds>) | warning |
| Google Chrome is not installed (turno-browser) | Google Chrome not found | failure |
| The test launch of Chrome failed | smoke launch failed: <first line> | failure |
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):
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 33msWhen doctor finds nothing
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 lineIf 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 or open an issue with the output of turno doctor --report, which holds no tokens or secret values.