Skip to main content

​
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.