> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev.byterover.dev/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
brv webui --port 8090
```

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

```bash theme={null}
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:

```bash theme={null}
brv restart
```

Then re-run `brv webui`. If the problem repeats, see [daemon-first architecture](/daemon-first-architecture/overview) 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-web-ui/providers-and-models). 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 (<kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>R</kbd>) to bypass the PWA cache. If that doesn't work, restart the daemon:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
brv status --format json
```

Look for the `logPath` field in the output.