Troubleshooting

Fix common issues with the local web UI

Port already in use

Symptom: brv webui fails with a port-bind error, or the browser opens a stale page served by another process.

Fix: pass a different port. The daemon remembers the new choice, so this is a one-time change.

brv webui --port 8090

If the daemon thinks the old port is still valid, restart it:

brv restart
brv webui

Daemon not running

Symptom: brv webui prints Failed to get web UI port. Use \brv restart` to restart the daemon and try again`.

Fix: the daemon didn't auto-start, or it crashed. Restart it:

brv restart

Then re-run brv webui. If the problem repeats, see daemon-first architecture for lifecycle details.

Browser didn't open

Symptom: brv webui prints the URL but no browser window appears.

Fix: copy the printed URL (http://localhost:<port>) into your browser manually.

Push or pull is disabled

Symptom: the Push or Pull action is greyed out.

Fix: sign in to ByteRover from the provider dialog. Local actions — editing context files, running curate or query, committing locally — don't require sign-in.

OAuth popup blocked

Symptom: clicking Connect on an OAuth provider does nothing, or the popup closes instantly.

Fix: your browser blocked the popup. Allow popups for localhost:<port> in your browser settings, then retry. The dialog also surfaces a fallback link — click it to open the OAuth page in a regular tab.

Stale bundle after upgrade

Symptom: after upgrading brv, the web UI shows an old layout or crashes on load.

Fix: the daemon is serving a cached bundle from the previous version. Hard-reload the tab (Cmd/Ctrl + Shift + R) to bypass the PWA cache. If that doesn't work, restart the daemon:

brv restart
brv webui

Web UI loads but requests fail

Symptom: the shell renders but every tab shows an error like "request timed out" or "daemon disconnected".

Fix: the daemon's web socket is down while the HTTP server is up. Restart:

brv restart

If requests still fail, check for firewall rules or VPN software blocking localhost connections.

Refreshing a page (e.g. /contexts) returns 404

Symptom: the web UI works from the home page, but reloading a deeper route (like /contexts or /tasks) returns a 404 from the daemon.

Fix: this happened when brv was installed under a dotfile path (e.g. ~/.nvm/..., ~/.asdf/...) — the SPA fallback didn't match, so direct route loads fell through to a 404. Fixed in 3.8.3. Upgrade the CLI:

brv update   # or reinstall via your package manager
brv restart

Dialogs and sheets render unstyled

Symptom: shared components (dialogs, sheets, popovers) appear with no styling after installing brv from npm or another published package.

Fix: the Tailwind @source glob in an earlier build didn't match the installed layout of the shared UI package. Fixed in 3.8.2. Upgrade the CLI and hard-reload the tab to clear the cached bundle.

Still stuck?

File an issue with the daemon log attached. Find the log path via:

brv status --format json

Look for the logPath field in the output.