Troubleshooting¶

Fixes for provider setup, optional managed pairing, AI errors, scanning capabilities, and the dashboard. If something here doesn't match what you see, check raven-server --help (bare binary) or docker exec raven-pro raven-server --help (the current compiled Pro Docker image).

Two command prefixes

Everything below shows the bare-binary form (raven-server …). The current compiled Pro Docker image uses the same command name: raven-server auth status becomes docker exec raven-pro raven-server auth status. Add -it for interactive commands such as auth login. Source-based images use the raven CLI instead. See Install Raven.

Pairing & authentication¶

Pairing is for managed Chamber Door AI. Individual testing, basic reports, manual prompt exchange, and native BYO engagement analysis do not require it. Saving a BYO provider does not redirect managed advisor, chat, finding drafts, report writing, or REPL AI commands. See AI Analysis.

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

For a managed AI feature, this can mean the device isn't paired. Pair once per machine if you want to use that service:

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

Confirm it took:

raven-server auth status

For the managed connector, you should see chamberdoor (account-bound, rvn_pat_). If it shows not configured, pairing didn't complete. Re-run auth login and follow the URL all the way through. For native BYO analysis, check Settings → AI & privacy instead; for manual exchange, open AI Analysis and use the manual prompt workflow.

`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 Raven).
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.

Native BYO and manual analysis¶

Provider isn't configured or the connection test fails¶

Open Settings → AI & privacy, choose the provider, and save the model name and API key when required. OpenAI and Claude use their fixed hosted endpoints. Gemini uses Google's OpenAI-compatible endpoint; local or other servers must support OpenAI-compatible Chat Completions. Enter the API base URL, including /v1 when that server requires it.

The endpoint must be reachable from the Raven server, not only from your browser. In Docker, localhost refers to the Raven container; it does not refer to a model running elsewhere on your host. Use an address reachable from that container. A reachable compatible local model can work without internet access; hosted endpoints need a permitted internet connection. See Offline Mode.

Saving settings makes no provider request. Test provider connection sends a small test without engagement data and may incur provider charges. If it fails:

BYO_AUTH_FAILED: check the saved API key and access to the selected model. An AI-app subscription does not necessarily include API access.
BYO_RATE_LIMITED: check the provider's balance and rate limits. Chamber Door credits do not pay for BYO requests.
BYO_CONNECTION_FAILED or BYO_TIMEOUT: check the base URL, endpoint availability, and the Raven server's network access.

Changing the provider or endpoint clears the saved key unless you enter a replacement. Provider settings apply across engagements on this Raven installation; the saved key is kept in a private file on the Raven host, not in the encrypted credential database.

"This review expired or has already been used" / settings changed¶

A native BYO review is valid for 15 minutes and can be sent once. It belongs to the engagement where you prepared it. If you see BYO_REVIEW_EXPIRED, BYO_CONFIG_CHANGED, or BYO_WRONG_ENGAGEMENT, select the intended engagement and choose Prepare anonymized request again. Inspect the new prompt, destination, and model before sending.

Raven consumes the review before the provider request, so a failed send or timeout cannot reuse it. Prepare a fresh review before retrying; a timeout does not establish whether the provider processed or charged for the earlier request. Restarting the Raven server also discards prepared reviews.

Unsupported provider format or response¶

Native BYO accepts supported text completions: OpenAI Chat Completions, native Claude Messages, or the compatible format used by Gemini and local/other compatible servers. It does not request tools or switch providers automatically. BYO_INVALID_RESPONSE can mean the server returned no supported text completion. Changing a URL alone does not add support for another API format.

For BYO_OUTPUT_TRUNCATED, increase the output limit and prepare a new review. OpenAI and Claude require an explicit limit; Gemini and compatible servers can use their provider default. If a received response could not be saved to history, copy the response shown in Raven before leaving the page rather than paying to generate it again.

Use Use copy-and-paste instead in AI Analysis when you prefer an AI app, use an unsupported API format, or need the manual workflow after a failed direct request. Generate a fresh manual prompt, inspect it, copy it into your chosen model, and paste its text response back for local placeholder restoration. Manual exchange needs no saved provider, API key, Chamber Door pairing, or managed credits; your chosen model may have its own charges. This beta has no native subscription-based Copilot, Claude-app, or ChatGPT-app connector.

Privacy check stops request preparation or sending¶

If Raven says nothing was sent, review the engagement's privacy settings and source data before preparing another request. A known identifier embedded in a longer token may require registering the full sensitive term. Recognized identifiers and credential formats are checked locally, but redaction does not guarantee that every identifying detail is removed. Inspect each outgoing prompt before sharing it. See AI Analysis privacy and review limits.

AI errors (HTTP status codes)¶

These errors apply to managed Chamber Door AI, which meters requests against your managed credit balance. BYO errors are described above; provider authentication or balance failures do not require re-pairing with Chamber Door.

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¶

For a managed request, confirm the Raven server can reach Chamber Door and that the account has available managed credits. Native BYO requires access to its saved endpoint instead, and a compatible local model can work without internet access. Manual prompt generation and local response restoration make no model request. See Offline Mode.

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 Raven). 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.). Check the run's error/output and the selected execution machine's tool readiness. Use the individual Docker image for the bundled catalog when the host does not have the required toolchain. Download filenames containing pro do not require payment or pairing for individual testing.

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.

A previously connected agent disappears¶

If the dashboard first shows stale/last-seen status and then 0 agents, or a prepared job's Start button is disabled, check the existing connection before preparing another deployment:

Select the original engagement. Assigned agents belong to that engagement; changing the selected client does not move them.
Confirm the Raven controller and existing agent process are still running.
Check the agent's callback URL and server token. With a reverse SSH tunnel, 127.0.0.1 in the agent command means the forwarded port on the agent host; the tunnel's destination is the controller's Raven port.
Inspect the tunnel's terminal for a disconnected SSH session, refused forwarding, or a port collision. Restore the approved connection and wait for the same agent to show Connected before starting a new job.
If a job had started, review that run's output and stop state. An unconfirmed stop must remain unresolved until the executor acknowledges exit. Launching a replacement agent does not prove the original command stopped.

Follow Recover a lost agent connection for the full sequence. The manual placement example shows which machine owns each end of the tunnel. There is no need to change unrelated permissions, credentials, or firewall rules to diagnose this path.

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 Settings → Execution, choose This engagement for a client-specific jumpbox, set its authentication 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 Raven for the --host escape hatch and its warning.)

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

Raven's individual workflow is free to run. A legacy "Free" label does not disable local testing, manual exchange, or native BYO analysis. If the managed account status disagrees with your available credits, check the paired account and update an older image from the Downloads page (preserve your pentests/ and auth/ data; 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 runs without a LICENSE_KEY or paired account. 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),
# optionally pair for managed AI after startup:
docker exec -it raven-pro raven-server 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, reports, and local identifier maps are stored there. Protect backups and transfers as engagement data, and preserve the separate key for encrypted credentials. AI requests and manual prompt exchange share selected context when you choose to use them.
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¶

Engagement records are stored on the Raven host. For managed AI, selected context goes to Chamber Door's managed service along with account metadata such as tier, budget, and paired tokens. Native BYO sends the reviewed analysis text directly to your saved provider. For manual exchange, you decide where to copy the prompt.

Raven replaces known client, host, domain, IP, email, and account identifiers with placeholders locally and redacts recognized credential formats. Reversible identifier maps stay with the engagement on the Raven host; recognized response placeholders are restored locally, while redacted secrets cannot be restored. The map is not included in an AI request.

This is data minimization, not a guarantee of perfect anonymity. Unregistered names, unusual secret formats, and identifying technical context may remain. Review outgoing text, follow the engagement's data-handling rules, and consider the chosen provider's privacy policy. See AI Analysis.

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.