---
title: "Troubleshooting"
description: "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)