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 with docker exec -it raven-pro … and swap raven-server for raven, because the image installs the CLI as raven and has no raven-server on its PATH. 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 meters them against your credit balance. 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`)¶

Your AI credit balance is spent (or, on a trial, you hit the trial cap). Local work is unaffected: scans, findings, exports, and the basic report all keep working. Options:

If you're on a subscription, 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.)

Remote agent¶

Agent loops on "connection refused"¶

[WS] Connecting to ws://localhost:8080/ws/agent...
[WS] Connection failed: dial tcp [::1]:8080: connect: connection refused

Two separate causes, usually both at once:

Wrong port. Both default to 8080 from beta67 on, but if you started the server with -p, or you are on an older build where the server defaulted to 5000, pass a matching -server ws://127.0.0.1:<port>/ws/agent.
IPv6. localhost resolves to ::1 on most hosts, while the server binds IPv4 127.0.0.1. Note the [::1] in the error. Use the literal 127.0.0.1.

Agent connects, enumerates tools, then immediately disconnects¶

[AGENT] Connected, sending registration (root=true, engagement="")
[AGENT] Tool impacket-secretsdump present ...
[WS] Read error: websocket: close 1000 (normal)

The token was missing or wrong. From beta67 the server sends an explicit AUTH FAILED line before closing, so the agent says so directly. On earlier builds it closed silently and the log looked like a successful connection right up to the close: close 1000 immediately after registration means auth, not a network fault.

Most often the token expanded to an empty string, for example -token "$(raven-server auth agent-token)" where raven-server is not on PATH. Read the file directly instead:

sudo ./raven-agent -server ws://127.0.0.1:8080/ws/agent -token "$(cat ~/.raven/agent_token)"

See Remote Agent.

Jumpbox & SSH¶

`[Errno 2] No such file or directory: 'sshpass'`¶

Raven only shells out to sshpass when a jumpbox has a password set and no usable SSH key, and Kali does not ship sshpass by default. Rather than installing it, switch the jumpbox to key auth, which is the better answer on an engagement anyway:

ssh-keygen -t ed25519 -N '' -f ~/.ssh/raven_jump
ssh-copy-id -i ~/.ssh/raven_jump.pub user@jumpbox

Then in Config, Jumpbox card, set the auth toggle to Key and point it at ~/.ssh/raven_jump. Selecting Key is what matters: with a key configured, sshpass is never invoked. Clear the stored password once it works.

If the jumpbox is the Raven host itself, skip ssh-copy-id entirely:

mkdir -p ~/.ssh && cat ~/.ssh/raven_jump.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys && chmod 700 ~/.ssh

`ssh_askpass: exec(/usr/bin/ssh-askpass): No such file or directory`¶

ssh needed to prompt for a password but had no controlling terminal, so it fell back to a GUI askpass that is not installed. It usually means DISPLAY is set. Force the prompt back to the terminal:

unset DISPLAY SSH_ASKPASS && ssh-copy-id -i ~/.ssh/raven_jump.pub user@host

A trailing Permission denied (publickey,password) after this does not necessarily mean the password was wrong; askpass may have died before collecting one.

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¶

Raven is free to run, so "Free" is a normal state, not a fault: it means this server has no AI credits available to spend. If you do have credits and it still shows Free, 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, since 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, so only a token prefix shows) and the exact error text from the AI chat or UI.