Skip to main content

​
Troubleshooting

​
Start here

Prints versions, resolved paths, your settings, index facts per agent, SQLite’s own integrity verdict, and whether the index has drifted from what is on disk. It is strictly read-only — it will not create, migrate or touch an index, so it is safe to run against a broken one. It exits non-zero if the integrity check fails. Paste its output into any bug report; it is built for exactly that.

​
The browser did not open

Copy the whole UI: line from the terminal. The ?token= is required on every request, so 127.0.0.1:<port> alone will not authenticate. Over SSH, forward a fixed port:

​
Sessions are missing

Check the source lines the CLI printed at startup — the Codex and Cursor lines only appear when those directories exist. Empty sessions are hidden in the sidebar by default. Turn off “hide empty” in the filter popover. Deleted logs are reported honestly: the health card counts them and disk usage marks them “file gone”. Pruning is the one way to forget them.

​
Counts or costs look wrong

Costs are estimates from a shipped price table — see Spend for the two ways naive counting inflates them, and modelPricing to correct the rates. If the index looks stale, turnlog index runs an incremental pass; turnlog index --rebuild drops the derived tables and starts over. Your annotations survive a rebuild — pins, names, notes, tags, bookmarks and saved searches live in tables the rebuild does not touch.

​
The index takes more disk than you expected

The size on the health card counts the whole footprint — the database plus SQLite’s write-ahead log beside it, which is where recent writes sit before they are folded in. Turnlog truncates that log after every indexing pass, so the number comes down on its own; repack on the same card reclaims what a prune left behind. The other reason is deep search, which builds a second index for substring matching and costs a few times the first one. Dropping it from the health card gives that space straight back.

​
After an update, something looks odd

Some releases bump an adapter version, which forces a full re-index of that agent’s files on the next scan. That is expected and self-healing — it is how a parser fix reaches sessions that were indexed before it existed.

​
Windows: a leftover .turnlog-<random> directory

Versions up to 0.13.0 carried a native SQLite module, and npm cannot delete it while a running Turnlog — or an agent’s MCP process — has it loaded, so updating away from one of them can leave the old install behind and warn EPERM. The update itself succeeded. Turnlog sweeps the leftovers on its next start, when nothing holds them, and doctor reports any it finds without deleting them. Newer versions have no native module, so it does not happen again.

​
Nothing works and you want a clean slate

The index is disposable:
Your agents’ logs are untouched by this — Turnlog never wrote to them. You lose your annotations unless you exported them first: