Appearance
Troubleshooting
Common errors and how to resolve them
Why am I seeing "Agent initialization failed" or "Blob storage initialization error"?
Example errors:
```
Agent not initialized: Agent initialization failed: Blob storage initialization error: Fail
```
```
Failed to initialize SQLite storage: The module was compiled against a different Node.js version
```
NOTE
From version 2.3.2 onwards, the SQLite error above no longer occurs — the better-sqlite3 dependency was removed. If you see this error, updating to the latest version will resolve it.
**If you installed via the curl script**, this error should not occur because the binary bundles its own runtime. Re-run the install script to fix:
```bash
curl -fsSL https://byterover.dev/install.sh | sh
```
**If you installed via npm**, this is caused by a Node.js version mismatch — the CLI was installed with a different Node version than what's currently active.
**Solution:** Use Node.js >= 20 and reinstall:
```bash
# Check your Node version (should be v20+)
node --version
# If using nvm, switch to a supported version
nvm install 20 && nvm use 20
# Reinstall ByteRover CLI
npm uninstall -g byterover-cli
npm install -g byterover-cli
```
After reinstalling, run `brv restart` to start fresh.
Why does the TUI show "running:0" when a task is actually running?
Symptom:
A command (like `/query`) is visibly running in the REPL, but the TUI displays `running:0`.
**Cause:**
This typically happens when:
* The REPL has been kept active for a long time
* Your laptop went to sleep mode while the REPL was open
**Solution:**
Run `brv restart` to stop all processes and start fresh:
```bash
brv restart
```
Alternatively, press `Ctrl+C` to quit the current session and start a new one with `brv`.
I'm getting errors when using a third-party provider model. How do I fix it?
Third-party providers may return errors due to API key issues, unsupported features, rate limits, or model changes. The quickest fix is to switch back to ByteRover's built-in LLM — it's fully compatible with all ByteRover features. It requires a logged-in ByteRover account (no API key):
```bash
brv login -k <your-api-key>
brv providers connect byterover
```
Or in the REPL, run `/providers` and select **ByteRover** (you'll be prompted to sign in if not already logged in).
If you prefer to keep using an external provider, make sure to pick a model from the [recommended LLM list](/external-llm-providers/overview#recommended-llm-list) — these have been verified for full compatibility. To switch models:
```bash
# Switch to a verified model
brv model switch <model-id>
```
Or in the REPL, run `/model` to browse and select.
Below are specific errors and their workarounds.
***
**"Unsupported feature" or tool-use errors**
Not all models support tool use (function calling). If you see errors related to tool calls or unsupported features, switch to a model from the [recommended list](/external-llm-providers/overview#recommended-llm-list) — these have been verified to work with ByteRover's full feature set.
***
**Provider API is down or returning 500 errors**
This is on the provider's side. Check their status page (e.g., status.openai.com, status.anthropic.com) and switch to another provider in the meantime:
```bash
brv providers switch <another-provider>
```
***
**Streaming errors show `[object Object]` or unclear messages**
If you see `[object Object]` instead of a meaningful error message during streaming, update to v2.3.3 or later. This version improves error handling for provider streaming failures — particularly for models like GPT-5. While it may not catch every case, most streaming errors should now display a more useful message that helps you diagnose the issue.
***
**`brv providers connect` or `brv providers switch` shows success but provider doesn't work**
Prior to v2.5.1, these commands could report success even when the server rejected the request (e.g., due to missing authentication). Update to v2.5.1 or later — authentication and server-side errors are now correctly surfaced in the command output.
How do I configure ByteRover CLI to work behind a corporate proxy?
NOTE
Enterprise proxy support requires ByteRover CLI v2.4.0 or later.
ByteRover CLI automatically routes requests to ByteRover's internal services through your corporate proxy when the environment variables below are set. This covers cloud sync, hub registries, and authentication. Traffic to external LLM providers (OpenAI, Anthropic, OpenRouter, etc.) is **not** routed through the proxy. No CLI flags or configuration files are needed.
**Set these environment variables before running `brv`:**
| Variable | Purpose | Example |
| --------------------- | --------------------------------------------------- | ---------------------------------------- |
| `HTTPS_PROXY` | Proxy for HTTPS traffic | `http://proxy.corp.com:8080` |
| `HTTP_PROXY` | Proxy for HTTP traffic | `http://proxy.corp.com:8080` |
| `NO_PROXY` | Comma-separated list of hosts that bypass the proxy | `localhost,127.0.0.1,.internal.corp.com` |
| `NODE_EXTRA_CA_CERTS` | Path to corporate CA certificate for SSL inspection | `/etc/ssl/certs/corp-ca.pem` |
```bash
# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export HTTPS_PROXY=http://proxy.corp.com:8080
export HTTP_PROXY=http://proxy.corp.com:8080
export NO_PROXY=localhost,127.0.0.1
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
```
After setting these, requests to ByteRover cloud, hub, and authentication endpoints will route through the proxy.
***
**Common proxy errors and fixes:**
| Symptom | Likely cause | Fix |
| ------------------------------------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------- |
| `UNABLE_TO_VERIFY_LEAF_SIGNATURE`, `SELF_SIGNED_CERT_IN_CHAIN`, or `CERT_HAS_EXPIRED` | Corporate SSL inspection without a trusted CA cert | Set `NODE_EXTRA_CA_CERTS` to your corporate CA certificate path |
| Connection timeouts (`ECONNABORTED`, `ETIMEDOUT`, `ECONNREFUSED`) | Proxy not set or incorrect proxy URL | Verify `HTTPS_PROXY` is set and the proxy host/port are correct |
| `407 Proxy Authentication Required` | Proxy requires credentials | Include credentials in the URL: `http://user:pass@proxy.corp.com:8080` |
**Verify your proxy setup** by running a command that hits ByteRover's APIs:
```bash
brv login
```
If the CLI can authenticate successfully, your proxy configuration is working correctly.
NOTE
Proxy routing only applies to ByteRover's internal services — cloud sync, hub, and authentication. Traffic to external LLM providers (OpenAI, Anthropic, OpenRouter, etc.) is not routed through the proxy.
Commands like `brv query` and `brv curate` route through the proxy when using the ByteRover built-in provider. To set this up, run `brv login` followed by `brv providers connect byterover`.
TIP
If you previously experienced connection failures on corporate networks with HTTPS_PROXY set, update to v2.5.0 — this release fixes a proxy double-routing issue.
How do I diagnose issues with ByteRover?
Run brv status for a quick health check. It shows your CLI version, account state, current space, and context tree status:
```bash
brv status
```
**Common status messages and fixes:**
| Message | Fix |
| ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| "Daemon failed to start automatically" | Run `brv restart` |
| "Daemon crashed unexpectedly" | Run `brv restart` |
| "\[outdated, daemon vX.Y.Z]" tag in the REPL header, or MCP drift footer on `brv-query` / `brv-curate` responses | Run `brv restart` and restart your coding agent / IDE |
| "Account: Not connected" | Normal for local-only usage — no action needed |
If `brv restart` does not resolve the issue, try reinstalling:
```bash
# curl install
curl -fsSL https://byterover.dev/install.sh | sh
# npm install
npm uninstall -g byterover-cli && npm install -g byterover-cli
```