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.
Report a bug from any chat: @devs
In any chat with a bot, on the desktop app or on Brainwrite Cloud, type @devs (it is
the last entry in the @ list) and a few words about what went wrong, then send.
Typing it is the decision to send: there is nothing else to press.
The bot answering the message adds a short summary: what you said went wrong, what it saw itself in the conversation, and steps to reproduce. Brainwrite adds its own facts: the app version, the computer's system, whether it runs on the desktop or on Brainwrite Cloud, the bot's engine and model, recent errors in that conversation, the server's latest warnings and errors, and the conversation's ids. Keys, passwords, tokens, cookies and the parameters of web addresses are masked first. The rest of the conversation is never sent, and neither is any file.
A line in the chat says where it went, for example Sent to the Brainwrite team (report …). We get it by email and will reply to you@example.com. The reply address is the email you signed in with, or the one in your profile. We keep reports for 180 days.
If the report cannot go yet (no connection, or too many reports in the last hour), the line says so: the report is saved and sent on its own later, so there is no need to send it again.
Under your message, a short line follows the report: Bug report sent · Got it, we're looking, then, once it is fixed, Fixed in the version with the fix (or coming in your next update while you don't have it yet). When the update with the fix is installed, the chat says so once and asks whether you want to try again.
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.