Troubleshooting

Each heading below is a symptom. Find the one that matches what you are seeing and work from there.

The browser shows a login form on a fresh install

You cannot get past it, because no account exists yet. Normally the panel detects that and shows the setup wizard instead; if it shows the login form, the detection request failed.

The form says so when that happens: it warns that GET /api/v1/bootstrap could not be reached. Two causes:

• the server binary is older than the SPA it is serving, so the endpoint does not exist. Rebuild, or use a matching release.
• a proxy in front of the panel is not forwarding /api.

Check it directly:

curl -s http://127.0.0.1:7337/api/v1/bootstrap
# {"needs_setup":true}

The setup wizard never appears

It only appears while the database has no users, and it refuses to run once one exists. If you have an account but cannot get in, reset the password:

red-clippy reset-password --username alice --password 'new-one'

Run that on the server host, in the directory holding the database, or with --database-url pointing at it.

Nobody can sign in

Sign-in takes a username, a password, and an optional organization slug. The slug is only needed to pick a specific organization; leave it blank for your default. Getting the slug wrong is a common cause of a login that looks broken.

If you are sure the credentials are right, check you are talking to the database you think you are. The server prints its storage path at startup, and the database path comes from the same config.

The panel loads but every page is empty

You are probably in the wrong organization. The display name under the logo says which one. Switch from avatar menu > Organizations.

The MCP server is not connecting

Work through it in order:

1. Is red-clippy serve running? The MCP process is a proxy to it, not a replacement for it.

   curl -s http://127.0.0.1:7337/api/v1/health
   

2. Is the key valid? A revoked key fails on every call. Check its state in Settings > API keys.
3. Is the command path right? Your client launches the binary by path. red-clippy on its own only works if the binary is on the client’s PATH, which it usually is not. Copy the command from Connect MCP, where the path is filled in.
4. Run the Shell (manual test) snippet from that same section. It should sit and wait for input. If it exits immediately, the error it prints names the problem.

For Claude Code specifically, claude mcp list shows whether the server is connected.

An agent writes to the wrong engagement

Either the session is not pinned, or it is pinned to the wrong one. Pin it with --pentest or RED_CLIPPY_PENTEST, using the numeric id or the exact code. A code has to match exactly, including case.

Without a pin, write tools require an explicit pentest_id on every call, and an agent that guesses will guess wrong eventually.

An agent writes to the wrong client

An API key belongs to one organization, so this means the wrong key. Use one working folder per client with the MCP server added inside it, and launch the agent from that folder. See Connecting an agent over MCP.

A scan says the tool is not installed

The scan engine shells out to tools on the machine running red-clippy serve, not on your machine and not inside the agent’s environment. The Scanner page shows availability per tool and gives the install command:

Availability for the display is probed once at startup and cached, so a tool installed while the server is running still shows as missing until you restart. Launching a scan re-checks for real, so if you know it is there you can start the run anyway.

An import says the format is not recognised

The parser sniffs the content. Two things trip it up:

• nmap text or grepable output. Only XML (-oX) is consumable, because it is the only format carrying service, version and script results.
• subfinder output. A bare list of hostnames is too generic to detect safely, so it is only parsed when the format is named. Use the Subfinder card, or pass "format": "subfinder" to the API.

Ports appear twice

They should not: ports are matched on host, port and protocol, so a re-import updates rather than duplicates. If you are seeing two rows, check whether they differ in protocol or in host spelling. shop.northwind.test and the IP it resolves to count as different hosts.

Coverage went down after a recon run

Working as intended. The percentage counts every check across every asset you have opened, so opening new assets adds checks to the total.

“Reveal in file manager” does nothing

It is off unless local_open = true is set in the config file, and even then it opens a folder on the machine running the server. On a headless server there is no graphical session for it to open into. See Configuration.

An upload is rejected as too large

The default cap is 25 MiB per file. Raise max_upload_bytes in the config, or put the artefact in the Files area instead, which is the better home for a 120 MiB packet capture anyway.

Startup fails complaining about a config key

An unrecognised key is an error rather than a warning, so a typo cannot leave you quietly on a default. The message names the key. The valid ones are in Configuration.

Increasing log verbosity

RUST_LOG=debug ./red-clippy serve
RUST_LOG=info,sqlx=info ./red-clippy serve   # include SQL

Logs go to stderr.

Reporting a bug

Bug reports go to the issue tracker. Security issues should be reported privately instead, following SECURITY.md.