Common Issues
Use these fast checks before deep debugging. They cover most MVP demo failures.
API unreachable
Dashboard shows network errors / cannot load data.
- Run `bcli dev` and verify API process is running.
- Check `/api/v1/health` response from the same machine/browser network.
- Confirm `VITE_API_BASE` matches your active API endpoint.
Next: Open /overview after API recovers to confirm nodes and tasks are visible.
Auth 401 / admin locked
Actions fail with unauthorized / token mismatch.
- Set/update token in the Admin badge (top/side).
- Verify `MEGABRAIN_ADMIN_TOKEN` on API side.
- Retry the same action after token refresh.
Next: Use /security/overview to confirm auth posture.
Node offline
No online nodes; jobs stay pending.
- Check /agents (Nodes tab) for heartbeat age and status.
- Restart node agent (`bcli node start` on node host).
- Confirm node can reach API endpoint and has valid bearer token.
Next: Re-run job from /chat or /ops after node returns online.
Tunnel failure
Preview URLs fail or service routes do not resolve.
- From a feature worktree: run `scripts/worktree-tunnel-up.sh --prefix wkui --tunnel-api prod`.
- Verify local dashboard is alive on the selected worktree port.
- Verify the public URL returns 200/307; if not, run `scripts/worktree-tunnel-down.sh --prefix wkui` and retry.
Next: Validate route by opening the generated public URL.
Agent orchestration stalled
Task stays Running/Pending and chat pipeline does not advance.
- Use Brick chat `fetch: daemon_state` and `fetch: acsm_agents` to verify runtime state.
- Run `create_git_job` before agent directives if repo/workdir state is stale on node.
- Check `/jobs` events/logs for the active run/job and confirm node_id/workdir are correct.
Next: If task is review-gated, move it through `/review` (or `review_task`) to continue the pipeline.
Migration drift
API boots but DB endpoints fail unexpectedly.
- Check `cargo run -p brick-cli -- db status`.
- Confirm `DATABASE_URL` points to intended DB.
- Run migrations and restart API service.
Next: Open /overview and verify API + DB health indicators.