Troubleshooting
Find the failing layer first, then apply the smallest safe fix.
Most Brainwrite failures come from one of four layers: the desktop app, a local agent CLI, a connected service, or a computer backend.
Where are my logs?
Where the logs are on Windows, macOS and Linux, and how to share them with secrets removed.
App startup and ports
App will not open, local server is unavailable, or a port is occupied.
Agent engines
CLI missing, model unavailable, authentication failure, or reconnect loop.
Connected apps
OAuth completes but tools do not appear or an account disconnects.
Desktop updates
Download spins, restart does nothing, or the new version does not launch.
Google sign-in in a cloud browser
A passkey sign-in stops at “Verifying it’s you” in a bot’s browser.
Collect useful evidence
Before opening an issue, record:
- Brainwrite version and operating system;
- selected engine and model;
- the exact visible error, not only “it failed”;
- whether the same agent CLI works directly in a terminal;
- whether restarting only the affected task changes the result;
- the file from Settings → General → Diagnostics → Export Diagnostics…, which removes keys and passwords (see Where are my logs?).
Never post API keys, OAuth callback URLs, bearer tokens, or the contents of secure credential files.