Troubleshooting

Most of what is below starts in Status, which shows what Chestnut's background work and your library have been doing, and what is stuck. Its System & Diagnostics section, collapsed at first, holds the version, the database and log locations, and the repair tools.

The app says it is disconnected

Chestnut's window talks to a process running in the background on your machine. When that process is not reachable, the window shows a Connection Lost screen rather than empty panels that look like missing data.

Try, in order:

1. Wait a few seconds. The app reconnects on its own, or click Retry Now to check again straight away.
2. Read the Connection Lost screen: any error under Reconnecting… is why the app could not reach its background process.
3. Quit Chestnut fully and reopen it, which restarts that process with it.

If it keeps happening, report it from inside Chestnut. Use the round Help button in the corner of the window (or Help at the bottom of the rail once the app is back), then Send feedback; Help → Send Feedback… in the menu bar opens the same dialog. Say whether it is a Bug report or a Feature request, describe what happened, and pick where it goes:

• Report publicly on GitHub opens a prefilled issue in your browser, carrying your app version, operating system and processor type but never any logs. A long report is copied to the clipboard for you to paste.
• Send privately to the Chestnut team reaches us directly and lets you attach diagnostic logs, after showing you exactly what they contain. It needs you to be signed in.

Include what the Connection Lost screen said either way.

The window says it crashed

If the part of Chestnut that draws the window crashes, Chestnut reloads the window by itself and your sessions come back, because they run outside the window. If it crashes again within a minute of that reload, Chestnut stops reloading and shows a page saying the window crashed, with a Reload button. Your sessions are still running behind it; click Reload to get back to them.

Each crash is written to Chestnut's log with its cause and how much memory the window was using, so if this happens more than once, report it from Help and choose Send privately to the Chestnut team with diagnostic logs attached.

A conversation I just had is not in the list

New conversations arrive through a background import rather than instantly. Check the file watcher in the status bar along the bottom of the window. While it reads Scanning, new conversations are still being imported; click it to see progress.

If the conversation ran in a directory Chestnut has never seen, it still gets imported. Check the filter pickers beside the search box in Conversations (type, project, date range and session kinds): any of them can hide a conversation that was imported.

Search is not finding something I know is there

Search runs against a text index over your conversations. If the index has fallen behind or been damaged, search misses content that is genuinely present.

Open Status, expand System & Diagnostics, and choose Rebuild search index. Rebuilding reads your existing conversations again and does not contact the network or lose data. It can take a while on a large history.

Try this when search returns nothing for a phrase you can see with your own eyes in a conversation you have open.

A summary is out of date

Summaries are generated, not live. The panel on the right of a conversation says Up to date or how many messages behind its summary is, so a conversation that grew since its last summary is marked as such rather than quietly serving a stale overview.

Open the conversation and choose Re-analyze in that panel.

Sessions will not start

If sessions fail to start immediately:

• Check that the agent's command (claude, codex or opencode) still works in an ordinary terminal. Chestnut runs the same command you would.
• For Codex or OpenCode, open Settings > CLI backends. Check that the agent is switched on, and read the reason shown under it if it cannot start, for example that its command was not found on your PATH. If the command lives somewhere else, enter its full path in the agent's command field.
• Check the arguments you added: Settings > Launch defaults for Claude Code, and each agent's Extra arguments in Settings > CLI backends for Codex and OpenCode. An argument the agent does not accept fails every session, including the ones that worked yesterday.
• Check whether the project you are launching in has its own arguments. A project's arguments replace the global ones rather than adding to them, so the two can disagree.

If you set environment variables for sessions and one of them is a name Chestnut reserves, the session fails to start and names the variable it refused. Remove that line.

News cannot load

The News panel fetches posts from the website. If it says "Couldn't check for updates. Showing saved posts.", the app could not reach the website; choose Try again. That is usually a network problem rather than an app problem, and it affects nothing else: your history, your search, and your sessions are all local.

I signed in with Google and my plan looks wrong

If you press Continue with Google on the address you already use, you should land on the account you already have, with the plan you already pay for. If you see a Free account where you expected Pro, do not buy a second plan. Send feedback from the Help panel in the app, choosing Send privately to the Chestnut team, and say which address you used and which button you pressed.

If sign-in stops before it finishes and shows a short message asking you to get in touch, Chestnut could not safely sign you in to that account. Contact us at the address the message gives, and say which address you used and which button you pressed.

Getting help

If none of this covers it, report it from the Help panel in the app with Send feedback. On Chestnut Pro you can also email us: the address is on the Help page of your account on the website. Tell us what you were doing, what happened instead, the Chestnut version from Settings > About & updates, and your macOS version. Those four things usually save a round trip.