Troubleshooting

"Provider is unavailable or cannot serve model"

The chat is pinned to a model whose provider is not enabled, has no credential, or does not list that model.

Tidebreak does not fail over to another provider. A foreground turn stays on the model you chose and refuses loudly rather than quietly answering from somewhere else. Fix the provider in Settings → Providers, or change the model on the chat.

The agent says it cannot run commands

Code execution has no backend selected. On macOS the local sandbox is used automatically; on Windows and Linux you must configure one — Docker, E2B, or Daytona — under Settings → Code execution.

If Docker is selected, check that the container runtime is actually running.

A package install fails

pip install needs the chat's network policy to be Package installs or wider. Set it from the composer's Tools → Network. See Code execution.

Search does not work on a Gemini model

Gemini models in Tidebreak do not use a provider-side search. With Search mode on Automatic and no search key saved, there is nothing for the tool to call. Add a key under Settings → Web search, or run that chat on an Anthropic or OpenAI model.

macOS keeps asking for keychain access

macOS ties keychain approvals to a binary's code signature. After an update, or when switching between a release build and one you built yourself, previously stored credentials belong to a different signature.

Re-enter the credential, or rewrite each stored item under the running binary's signature. The CLI is not on your PATH. Use the copy inside the app:

/Applications/Tidebreak.app/Contents/MacOS/tidebreak rehome-secrets

If you built from source, run it through Cargo so the macOS signing runner applies:

cargo run -p tidebreak-cli -- rehome-secrets

The app will not start, or reports the data directory is in use

One process owns the application data directory at a time, enforced with a lock file. Close the other instance — including a headless tidebreak serve, or a CLI command run with --embed, started without TIDEBREAK_DATA_DIR: both use the app's data directory.

Chats disappeared after an update

Desktop upgrades from v0.61.0 onward keep your chats. Tidebreak upgrades the local database in place. Before an update changes the database, Tidebreak saves a copy in the backups/ folder of the application data directory.

If chats are missing after an update, look in backups/:

• pre-migration-<version>-<time>.db is the database as it was before an update changed it. Tidebreak keeps the two newest.
• unrecognized-<time>/ holds a profile that Tidebreak could not open, such as one from v0.60.0 or earlier. Tidebreak moved it aside, started a fresh profile, and wrote the folder's path to logs/tidebreak.log.

To restore a backup:

1. Quit Tidebreak.
2. Move tidebreak.db, tidebreak.db-wal, and tidebreak.db-shm out of the application data directory.
3. Copy the backup into the application data directory. Rename a pre-migration-… file to tidebreak.db. From an unrecognized-… folder, copy every file and folder it holds.
4. Open a Tidebreak version that can read the backup. For a pre-migration-… copy, that is the version you used before the update, or a later one. For an unrecognized-… folder, it is the version that wrote the profile.

Tidebreak says the profile was written by a newer version

You opened an older version of Tidebreak than the one that last used this profile. Tidebreak changes nothing and stops. Install the newer version again, or restore a backup from backups/ with the steps above.

A CLI you built from source counts as a version too. If it is newer than the app and you ran tidebreak serve or a command with --embed without TIDEBREAK_DATA_DIR, it upgraded the app's database. See Running headless.

Keys are missing from a CLI profile after an update

A profile you name with TIDEBREAK_DATA_DIR used to share the app's keychain entry. It now has an entry of its own, and after the update that entry is empty. To copy the keys the profile stored before into it, run this once:

TIDEBREAK_DATA_DIR=/path/to/profile tidebreak rehome-secrets

The app's entry stays as it is. The copy holds the app's keys too, because the two shared one entry; remove any the profile should not use with tidebreak provider remove-key. See Running headless.

Closing the window did not quit Tidebreak

On macOS, the close button hides the window and leaves Tidebreak running, so agents keep working. To bring the window back, click Tidebreak in the Dock or choose Window → Tidebreak. To quit, press ⌘Q.

If agents are working when you quit, Tidebreak asks first. Quit and stop them ends their current turns. Quit when they reach a safe point lets code turns finish and picks chats up again the next time Tidebreak opens. Logging out or shutting down never waits on this question.

An agent waiting for your answer to an approval, a question, or a plan reaches a safe point only after you answer, so the question says so and offers the inbox. While Tidebreak waits for a safe point, a bar at the bottom of the window counts the agents down, and you can keep using the app to answer them.

"Tidebreak quit unexpectedly"

This notice appears when the last run ended without quitting normally: a crash, a force quit, or a power loss. Save diagnostics report writes a ZIP file where you choose. It holds a process snapshot and recent log lines, including any crash reports. It does not read chats, files, or credentials, and error messages in it have URL queries, tokens, and credentials removed. Log lines can still name local paths, so look it over before you share it. Nothing is sent anywhere; attach the file to an issue if you want help.

Reporting a problem

The chat header menu has Copy debug info and Save debug bundle…. Attach the bundle to a GitHub issue — it carries what is needed to reconstruct the turn.

Logs are at logs/tidebreak.log inside the application data directory, and crash reports are in boot-failures.log beside it.