Skip to Content

Troubleshooting

Troubleshooting

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

View source

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

FindingWhat doctor printsLevel
Node.js is too oldnode <node>, and turno needs 20 or newerfailure
An agent that profiles use is not installed<command> not found on PATH, and profiles use itfailure
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 installedGoogle Chrome not found: claude.ai links open in the default browserwarning
The launchers were written by another turno versionturno <version> runs, but <recorded> set up the launcherswarning
A service account has no read_toolsaccounts without read_tools: <no reads>; delegated reads get every tool of the account and ask like writeswarning
An agent's default or fallback names a profile of another agentagents.<id>.<role> = "<name>", but <name> is a <label> profilewarning
default or fallback names a profile that is not Claude Code<role> = "<name>" is for <label>, but <name> is a <label> profilewarning
A folder rule uses a profile that does not existthe rule for <path> uses profile <profile>, which does not existwarning
A profile has no launcherprofile <name>: no launcher <launcher>failure
A file with the launcher's name was not written by turnoprofile <name>: <launcher> was not generated by turnofailure
A launcher is out of dateprofile <name>: <stale>warning
A profile's folder does not existprofile <name>: <dir> does not existfailure
A shared item is a local copy in one profileprofile <name>: <item> is a local copy, not sharedwarning
A profile is missing the link to a shared itemprofile <name>: missing link for <item>warning
An agent-specific profile warningprofile <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 herewarning
A server runs outside the gateway<name> runs outside mcpdwarning
A remote server needs a login<server><@<variant>> OAuth: <text>warning
The gateway's service file has no programmcpd: <shown> has no program to runfailure
The gateway's service file runs a program that is gonemcpd: <shown> runs <missing>, which no longer existsfailure
The gateway's service file runs a versioned pathmcpd: <shown> runs a versioned path (<program>) that breaks when that version is removedwarning
The LaunchAgent runs as a Background processmcpd: the LaunchAgent runs as a Background process, which macOS throttleswarning
A gateway file belongs to another usermcpd: <file> belongs to uid <uid>failure
A gateway token file is readable by othersmcpd: <file> is readable by others (mode <st>)warning
The gateway port answers with your token but belongs to another usermcpd: port <port> answers with your token but belongs to uid <uid>failure
The process on the port is not the mcpd that answersmcpd: port <port> is held by pid <pid>, but mcpd reports pid <pid>warning
mcp.toml is invalid, and mcpd serves the last good copymcpd: mcp.toml is invalid, serving the <source>: <error>warning
config.toml is invalid, and mcpd uses defaultsmcpd: config.toml is invalid, mcpd uses defaults: <error>warning
Another process holds the gateway's portmcpd: port <port> is in use by <describe owner>, so mcpd cannot listen therefailure
The gateway's last start failedmcpd: last start failed at <at>: <message>warning
Synced configs point at another portmcpd: <off> synced config<s> point at port <seen> but mcpd uses <port> (<off>)warning
Synced configs still send the master tokenmcpd: <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 tokenmcpd: <stale> profile token<s> predate<s> the current gateway token (<stale>)warning
The gateway's service file cannot be readmcpd: cannot read the service file: <message>warning

turno doctor --security

FindingWhat doctor printsLevel
No secret store was foundsecret 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 filespermissions: <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 userpermissions: <foreign> item<s> under turno's folders belong to another user (a sudo run?): <foreign>warning
Another user holds the gateway's portmcpd port <port>: held by <describe owner>, another user, so sessions would send it the gateway tokenfailure
A process that is not mcpd holds the gateway's portmcpd port <port>: held by <describe owner>, which does not answer as mcpd, so sessions would send it the gateway tokenwarning
mcp.toml holds literal secretsliteral secrets in <mcp file>: <in manifest>warning
An agent config holds literal secretsliteral 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 dayswarning
An MCP server runs whatever version is newestMCP servers without an exact version: <loose>warning
The gateway token is oldthe 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 readaudit log: cannot read it: <message>warning
The audit log's hash chain is brokenaudit log: line <line>: <reason>failure

turno browser doctor

FindingWhat doctor printsLevel
A headed Chrome cannot open in an SSH sessionthis 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 Chromeno display: a headed Chrome cannot open herewarning
An identity's identity.json is invalididentity.json <problems>failure
A Chrome was left running with no serverChrome pid <pid> was left running on this profile with no serverwarning
A Chrome that turno did not start holds the profileChrome pid <pid> holds this profile, but no turno process doeswarning
An identity has a stale runtime lockstale 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 runthe 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 foundfailure
The test launch of Chrome failedsmoke 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):

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

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 or open an issue with the output of turno doctor --report, which holds no tokens or secret values.

On this page