Troubleshooting¶

Fixes for the issues that actually come up: pairing, AI errors, scanning capabilities, and the dashboard. If something here doesn't match what you see, the authoritative command reference is always raven-server --help (bare binary) or docker exec raven-pro raven --help (Docker).

Two command prefixes

Everything below shows the bare-binary form (raven-server …). In Docker, prefix the same command with docker exec -it raven-pro … (so raven-server auth status becomes docker exec raven-pro raven auth status). See Install & Pair.

Pairing & authentication¶

"AI features unavailable" / "no AI proxy configured"¶

This device isn't paired yet. AI routes through your Chamber Door account, and that link is established by pairing once per machine:

raven-server auth login            # bare binary
# docker exec -it raven-pro raven auth login   # Docker

Confirm it took:

raven-server auth status

You should see chamberdoor (account-bound, rvn_pat_). If it instead shows not configured, pairing didn't complete — re-run auth login and follow the URL all the way through.

`auth login` fails with `EXPIRED` or `TIMEOUT`¶

The device code expired before you confirmed in the browser (the code is good for ~10 minutes). Re-run raven-server auth login and confirm faster.

`auth login` fails with `DENIED`¶

You (or someone on the account) clicked Deny on the pairing screen. Re-run and click Confirm.

Pairing is lost after a restart¶

The pairing token lives in ~/.raven/auth.json. If it disappears on restart, the directory holding it wasn't persisted:

Docker: you didn't mount the auth volume, or mounted the wrong path. Check it:
```
docker inspect raven-pro | grep -A1 Mounts
```
You should see a host path mounted at /home/raven/.raven. If not, recreate the container with -v ~/raven/auth:/home/raven/.raven (see Install & Pair).
Bare binary: ~/.raven/ was wiped or you're running as a different user than you paired with. Re-pair with raven-server auth login.

Re-pairing from scratch¶

raven-server auth logout
raven-server auth login

logout clears the saved token; login starts a fresh device flow.

AI errors (HTTP status codes)¶

AI calls proxy through Chamber Door, which enforces your plan. When something is wrong, the error surfaces in the AI chat with an HTTP status and a code:

402 `BUDGET_EXHAUSTED` (trial: `TRIAL_CAP_REACHED`)¶

You've spent your plan's AI credit for the current period (or, on a trial, hit the trial cap). Options:

Wait for the next period to reset.
Buy a top-up pack from app.chamberdoorsecurity.com.

Budget draining faster than expected?

One chat message is usually many Anthropic calls — Claude works in a tool-use loop, running modules and reading results across several iterations per message. Autopilot mode iterates the most aggressively. If spend is high, prefer shorter, more targeted prompts, and check recent usage on the dashboard.

401 `INVALID_TOKEN`¶

The pairing token was revoked from the dashboard, or it expired. Re-pair:

raven-server auth logout
raven-server auth login

You can see and revoke device tokens at app.chamberdoorsecurity.com → Tokens.

AI calls fail but pairing looks fine¶

If auth status shows you're paired but AI calls still error, it's usually connectivity to Chamber Door. AI requires an outbound connection — see Offline Mode. Confirm the machine can reach the internet, then retry.

Scanning & capabilities¶

Scans fail with "permission denied" / nmap errors / container won't start¶

SYN scans and other raw-socket operations need extra Linux capabilities. The container must be started with:

--cap-add=NET_RAW --cap-add=NET_ADMIN

If you started it without these, stop and recreate the container with them (see Install & Pair). For the bare binary on Kali, run as a user with the capability or grant it to the tool, e.g.:

sudo setcap cap_net_raw+ep "$(command -v nmap)"

Tool-using modules silently do nothing (bare binary, non-Kali)¶

The bare raven-server binary uses the host's installed tools (nmap, nuclei, etc.). On a host without them, modules start but produce no results. Use the Pro Docker image (toolchain bundled) on anything that isn't Kali with the full toolchain installed.

nmap host discovery isn't seeing hosts on your LAN (Docker, Linux)¶

Bridge networking can hide LAN hosts. On Linux, run the container with --network host instead of -p 8080:8080 when you're scanning a network you're physically on. (This option doesn't apply on Docker Desktop for macOS/Windows, which use a VM.)

Dashboard & access¶

Can't reach the dashboard from another machine¶

The single-user server binds 127.0.0.1 on purpose — it has no authentication, so the loopback bind is what keeps it private. Don't expose it; tunnel instead:

ssh -L 8080:127.0.0.1:8080 user@host

Then browse http://localhost:8080 locally. (See Install & Pair for the --host escape hatch and its warning.)

Web UI shows "Free" even though you're paired¶

The server is running an old image that predates chamberdoor tier resolution. Pull the latest tarball/binary from the Downloads page and re-load it (your pentests/ and auth/ data survive — see Updating).

Port already in use¶

Something else holds the port. Either free it or pick another:

Docker: map a different host port, e.g. -p 9090:8080, then browse localhost:9090.
Bare binary: raven-server start -p 9090 --no-browser.

macOS: "Operation not permitted" reading your pentests directory¶

Docker Desktop on macOS needs file-sharing permission for the directory you mount. Docker Desktop → Settings → Resources → File Sharing → add ~/raven (or your home directory).

Container keeps restarting¶

Check the logs — startup errors land there:

docker logs raven-pro

If the logs show License validation failed on a loop: you're running an old image. Single-user Raven Pro doesn't use a LICENSE_KEY — it pairs with your Chamber Door account at runtime, and the boot-time license check that produced this error was removed. Setting a token as LICENSE_KEY won't help either. Stop the loop, pull the latest image, and re-run without a license key:

docker rm -f raven-pro                          # stop the restart loop
gunzip -c raven-pro-*.tar.gz | docker load      # latest tarball from Downloads
# re-run the container WITHOUT any -e LICENSE_KEY=… (see Install & Pair),
# then pair:
docker exec -it raven-pro raven auth login

If an older note told you to set a LICENSE_KEY, that instruction is stale — drop it.

Data & storage¶

Where your data lives: whatever directory you mounted to /home/raven/pentests (the guides use ~/raven/pentests/). SQLite databases, scan output, screenshots, and reports are all there. Back it up like any working data — it never leaves your machine.
Database locked: another Raven process is holding the SQLite database. Stop the duplicate instance and retry. Don't run two servers against the same pentests/ directory.

What Chamber Door can and can't see¶

A frequent question, so to be explicit: your engagement data stays on your machine. Chamber Door receives only anonymized snippets for AI analysis (hosts, domains, emails, and usernames are replaced with placeholders on your machine before anything is sent, and the response is mapped back locally) plus account metadata (tier, budget, paired tokens). Raw engagement content is never sent.

Collecting info for support¶

When something's wrong and you need help, the most useful thing to include is the server log:

docker logs raven-pro --tail 50          # Docker
# or, bare binary: the output of the terminal running raven-server

Add your raven-server auth status output (it's masked — only a token prefix shows) and the exact error text from the AI chat or UI.