Troubleshooting

Common issues, where the logs live, and the startup switches.

When something breaks, start with two places: the logs and the startup flags. Most issues are traceable there.

Where the logs are

Scenario	Location
Tray mode (default)	`.bi/logs/web.log` (overwritten on every start; no history kept)
Console mode	Terminal output
Permission approval trail	`.bi/permissions.log` (full arguments of every gated tool call, JSONL)
Network activity log	`.bi/logs/network/*.jsonl` (requires `network_log_enabled`)

Startup flags and env vars

Flag	Purpose
`-no-tray`	Disable the system tray, back to console mode (tests / unattended / debugging)
`-dedupe-sessions`	Clean up duplicate and empty sessions, then exit; preview only unless `-apply` is passed
`BI_NO_TRAY=1`	Same as `-no-tray`
`PORT`	Override the port from `config.json`

Common issues

Port already in use

On startup Bi tries to free the listening port by ending the foreign process (via netstat on Windows). If startup still fails, check:

Is another Bi instance already running?
Does the firewall allow it?
Change the port manually: config.json → port, or the PORT env var

The UI opened but the page is stale

The front end is a single inline file that changes with the version, served with Cache-Control: no-cache. If you still see an old UI, hard-refresh once (Ctrl+Shift+R).

Garbled Chinese

The terminal panel converts GBK→UTF-8, so garbling is rare there; it mostly appears when running commands directly in the Windows console, tied to the code page
Command output entering context goes through the same conversion

The agent won’t run commands / stuck at approval

Every tool call requires your approval by default. If no prompt appears at all:

Check whether permissions.json has enabled: false (that turns the whole approval mechanism off)
Check whether disabled_tools turned the tool off
Check whether an intercept rule blocked the command (a [INTERCEPTED] prefix returns as the tool result)

Model errors

Pinned mode (default: "<providerID>/<modelID>") does no failover — switch to auto for retries
In auto mode, once a token is emitted there is no switching — the error surfaces to the caller, but the next turn retries
401 / 429 / 5xx put the model into cooldown (120s by default); it is not a candidate during cooldown

Sessions gone / messages missing

Session data lives in .bi/bi.db; don’t delete that file
-dedupe-sessions cleans up duplicate and empty sessions — preview the output first to see the impact
Export: POST /api/user/sessions/{id}/export writes the session as Markdown in the workspace

Disk usage is unusually large

.bi/checkpoints/ is the “roll back to this step” workspace shadow Git repo and grows with conversations; each snapshot contains the full workspace (minus ignored dirs). To reclaim space:

Delete old snapshots for the session under .bi/checkpoints/ once you no longer need them
To control size, add large directories to the fileutil ignore list so they never enter snapshots

Still stuck

Bring these with you:

The relevant excerpt from .bi/logs/web.log
bi --version output
Reproduction steps (what triggered it)
A config summary (base_url, model, workspace — leave out any keys)