Troubleshooting
App startup and ports
Diagnose launch failures and local server conflicts.
The Electron app starts a local harness and serves the interface from the same machine. The normal port is 8799. If another process already owns it, packaged builds may select a fallback port automatically.
App opens but never becomes ready
- Quit every Brainwrite window.
- Confirm no old Brainwrite process remains.
- Start the app once and wait for the local harness.
- If it still fails, inspect the desktop log.
On macOS, packaged logs are under ~/Library/Logs/Brainwrite. On Windows they are under the Brainwrite log directory in %APPDATA%.
Development port overrides
Use BWB_PORT for a source-run harness. A packaged desktop build owns its server lifecycle and may choose a fallback if the preferred port is unavailable.
Isolate a test profile
Developers can set BWB_DATA_DIR to run against a clean Brainwrite data directory. This is useful for reproduction and screenshots without touching a real workspace.