Docs / Troubleshooting
Troubleshooting
Common problems and the command that fixes each one.
Install and catalog
command not found: flanner
The install went somewhere not on your PATH. Run it as a module to confirm it is installed at all, then fix the PATH or reinstall.
python -m flanner.cli --helpDatabase not initialized
Run flanner init from inside the repository you want to adopt. The catalog lives at ~/.flanner/data.db.
flanner initPlan files are not showing up
flanner sync imports plan files that already carry a flanner header, for example after restoring .plans/ from a backup, and skips any Markdown file without one. For a plan of your own, ask your agent to save it through flanner, or paste it into the web interface. Sync is also what flanner init --sync does when adopting a repository somebody else set up.
flanner syncSomething is inconsistent and you cannot say what
doctor checks the catalog against the files on disk and reports what it finds: missing files, unreadable ones, hash mismatches, and whether the search index is available.
flanner doctorAgents
Your agent does not see the MCP server
Redo the registration with every agent, then restart the agent so it reloads its config. Claude Code, Claude Desktop and Codex each read a different file, and setup writes all three.
flanner setupThe agent is not saving plans through Flanner
Registration may not have taken. flanner status shows one row per agent, each checked where that agent actually looks.
flanner statusCodex is not picking it up
flanner init adds its entry to ~/.codex/config.toml when Codex is installed. If you installed Codex afterwards, or init could not edit the file safely, run flanner setup to try again, or add the two lines from the agents page yourself. Then restart Codex.
Messages do not show up in your agent
Run flanner init after you join your team: it adds the messages hook only on a device whose plan includes messages. In Codex, run /hooks once so Codex trusts the hook. If your administrator allows only managed hooks, give them what flanner init --print-codex-hook prints. flanner setup does not add the hook.
flanner initflanner status says this device is not receiving
Messages arrive, and your queued ones are resent, only while flanner peer serve runs. Autostart starts it now and at every login. If it says your system could not start the service, flanner peer start receives until you restart.
flanner peer autostart onCurb
flanner curb show says “there is no desktop session here”
The full report opens in a window, and a window needs a desktop. On Linux, show found neither DISPLAY nor WAYLAND_DISPLAY, as happens over SSH. Run it at the machine itself. The redacted report works anywhere.
flanner curb mapflanner curb show says “Python's Tk support is missing”
The window is drawn with Python's own Tk, and this Python was built without it. On Linux, install your distribution's python3-tk package, then run show again. Nothing is printed in the meantime.
No sweep: the leak sweep needs Kingfisher, which is not installed
The sweep's detector is an optional extra. Install it into the same Python environment flanner runs in. Nothing was read.
pip install 'flanner[sweep]'The sweep lists files over 64 MB under “Not checked”
The sweep reads one file at a time and skips any over 64 MB, to keep its memory use bounded. It counts them rather than hiding them. Secrets in those files are not counted, and no option raises the limit.
No approval method on this machine, so Curb stays read-only
Every change needs a yes from your operating system, and Curb found no way to ask: no desktop session, or no Windows Hello, Touch ID, password prompt or polkit. On Linux it needs a desktop session with polkit. Nothing is written. This lists the changes for you to make by hand.
flanner curb fix --dry-runNot approved, so nothing changed
The prompt was refused, or nobody answered it within two minutes. Nothing was written. Run the command again, and approve the prompt your operating system shows.
Not asked: three approvals were refused or ignored in ten minutes
Curb pauses every request for an hour, and the message says when it will ask again. The pause lifts on its own. If you did not start those requests, something on this machine did: look at what your agents are running.
flanner curb test says “inconclusive”
Nothing was proved either way. The agent declined, the call never ran, the run failed, or a prompt nobody answered stopped it. It is never counted as blocked. If every method is inconclusive, the run itself failed: check the agent is installed and signed in, then test again.
flanner curb testCurb could not edit Codex's config.toml safely
Curb changes Codex's config one line at a time, so your comments survive. A value written across several lines cannot be changed that way. Nothing is written to the file. The fix lists the same changes for you to make by hand.
flanner curb fix --undo left a file as it was
Undo only puts a file back while it still holds what Curb wrote. You have edited this one since, by hand or with another tool, and putting the copy back would lose that edit. The copy stays in ~/.flanner/curb/backups/ for 7 days from the fix.
Team and syncing
Syncing is slow
If peer status reports a relayed rather than direct connection, a firewall is refusing to be traversed. It still works, just slower.
flanner peer statusA teammate cannot reach you
Both machines have to be signed in, and the device has to appear under Devices in your team console. A revoked device cannot be dialled at all. Serving in the foreground also stops when you close the terminal — flanner peer start keeps it running. flanner peer autostart on starts it each time you log in.
flanner peer startA workspace you were granted is not listed
Entitlements last a day and renew on their own, so a new grant can take until tomorrow to arrive. This fetches it now.
flanner whoami --refreshStill stuck
Open an issue on GitHub. Include the output of flanner doctor --report, a scrubbed summary made for pasting into an issue, and flanner status. Between them they cover almost everything anybody would ask you for.