# How to Troubleshoot Common VulnClaw Errors: A Complete Guide

> Troubleshoot common VulnClaw errors like missing API keys or corrupted snapshots. Learn to fix these issues with vulnclaw doctor and configuration checks. Resolve VulnClaw problems fast.

- Repository: [Unclecheng/VulnClaw](https://github.com/Unclecheng-li/VulnClaw)
- Tags: how-to-guide
- Published: 2026-07-03

---

**Most VulnClaw errors stem from missing API keys, disabled MCP services, or corrupted session snapshots, and can be resolved by running `vulnclaw doctor`, verifying configuration files, and ensuring external dependencies like Chrome or Burp are properly configured.**

VulnClaw is a modular AI-driven penetration-testing framework built on three distinct layers: the CLI/UI frontend, the Agent Core, and the MCP Toolchain. Runtime problems typically surface in one of these layers as specific HTTP exceptions, file-not-found errors, or configuration validation failures. This guide maps the most frequent error messages to their exact locations in the source code and provides concrete resolution steps.

## Configuration and Environment Errors

Authentication and environment setup issues are the first gatekeepers to pass when running VulnClaw. These errors surface in [`vulnclaw/web/app.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/web/app.py) and [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py) before the agent loop even begins.

**Missing or malformed API keys** trigger `RuntimeError: HTTPException(status_code=401, detail="Invalid API key")` when the `VULNCLAW_LLM_API_KEY` environment variable is empty or invalid. In [`vulnclaw/web/app.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/web/app.py), the framework creates an `HTTPException` for auth failures at line 32.

**Unsupported Python versions** raise `SystemError: Python 3.9 is not supported` because [`vulnclaw/__init__.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/__init__.py) explicitly checks `sys.version_info` and requires Python 3.10 or higher.

**Invalid provider names** generate `ValueError: Unknown provider 'foo'` when the provider string does not match the enumeration defined in [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py).

To resolve these issues:

```bash

# Verify and export the API key

export VULNCLAW_LLM_API_KEY="sk-xxxxx"

# Check Python version (must be >= 3.10)

python3 --version

# List valid providers and set one

vulnclaw config provider list
vulnclaw config provider openai

```

Run `vulnclaw doctor` to execute the health-check routine in [`vulnclaw/doctor.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/doctor.py), which prints the detected Python version, LLM configuration, and MCP status.

## MCP Service Errors

The MCP (Model Context Protocol) Toolchain in [`vulnclaw/mcp/registry.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/registry.py) and [`vulnclaw/mcp/lifecycle.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/lifecycle.py) manages external services including fetch, memory, Chrome DevTools, and Burp. Failures here manifest as service-unavailable errors.

**"Fetch service unavailable"** appears as `HTTPException(status_code=503, detail="fetch service not enabled")` when the fetch MCP server is disabled or the `npx` binary is missing. The registry raises this in [`vulnclaw/mcp/registry.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/registry.py) when the service is not registered.

**"Chrome not reachable"** indicates a `RuntimeError` when Chrome is not started on the expected remote-debug port or the MCP command path is misconfigured. The lifecycle manager in [`vulnclaw/mcp/lifecycle.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/lifecycle.py) handles these connection errors through the `_is_benign_shutdown_exception` function.

**"Burp MCP JAR not found"** raises `FileNotFoundError` when `burp-mcp-all.jar` is missing or the path in `~/.vulnclaw/config.yaml` is invalid. The lifecycle loader checks this path during initialization.

Enable these services with the following commands:

```bash

# Enable fetch service

vulnclaw config set mcp.servers.fetch.enabled true

# Start Chrome with remote debugging

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug &
vulnclaw config set mcp.servers.chrome-devtools.enabled true

# Build and configure Burp MCP (requires Java 11+)

git clone https://github.com/PortSwigger/mcp-server.git ~/.vulnclaw/burp-mcp
cd ~/.vulnclaw/burp-mcp && ./gradlew embedProxyJar
vulnclaw config set mcp.servers.burp.enabled true
vulnclaw config set mcp.servers.burp.transport.command java
vulnclaw config set mcp.servers.burp.transport.args '["-jar","~/.vulnclaw/burp-mcp-all.jar"]'

```

Always restart the CLI after configuration changes and verify status with `vulnclaw doctor`.

## Target State and Snapshot Errors

The Agent Core persists target state through snapshots stored in `~/.vulnclaw/sessions/`. Errors here surface in [`vulnclaw/web/app.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/web/app.py) and [`vulnclaw/target_state/store.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/target_state/store.py).

**"Task not found"** (`HTTPException(status_code=404)` at line 117 in [`vulnclaw/web/app.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/web/app.py)) occurs when the task ID does not exist in the session cache managed by [`vulnclaw/web/task_manager.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/web/task_manager.py).

**"Snapshot not found"** (`HTTPException(status_code=404)` at line 180) indicates no snapshot exists for the given `snapshot_id`.

**"Session restore failed"** raises `RuntimeError: SessionRestoreResult.restored == False` when `apply_target_state_to_agent` cannot locate a valid state file in [`vulnclaw/target_state/store.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/target_state/store.py).

Resolution steps:

1. Inspect the session directory (`~/.vulnclaw/sessions/`) for `*.json` snapshot files.
2. Confirm the target name matches exactly (case-sensitive).
3. Resume with the correct snapshot ID:

```bash
vulnclaw run 10.0.0.5 --resume --snapshot-id 2024-07-03_01

```

4. List running tasks to verify IDs:

```bash
vulnclaw task list

```

5. If the cache is corrupted, reinitialize:

```bash
rm -rf ~/.vulnclaw/sessions/*
vulnclaw init

```

## Permission and Access Errors

Access control errors occur at the LLM provider level or within the agent's constraint system.

**"403 Forbidden"** (`HTTPException(status_code=403)` at line 200 in [`vulnclaw/web/app.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/web/app.py)) indicates the LLM provider rejected the request due to quota limits or IP blocks.

**"Tool call blocked by constraint"** raises `RuntimeError: Action prohibited by session constraints` when the session's `session.constraints` block the invoked tool. This is enforced in [`vulnclaw/agent/solver.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/agent/solver.py) during the explore phase.

To fix quota issues, verify provider limits with `vulnclaw config get llm.provider` or enable keyless ChatGPT login via `vulnclaw login`. For constraint errors, review and update permissions:

```bash
vulnclaw config get session.constraints
vulnclaw config set session.constraints.allow '["recon","scan","exploit"]'

```

Restart the run after updating configuration.

## Runtime Exceptions in the Agent Loop

Uncaught exceptions during the solve cycle bubble up to `run_agent_task` in [`vulnclaw/orchestrator.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/orchestrator.py) at line 23. Common patterns include:

- **ExceptionGroup** with "tool failed": Occurs during parallel intent exploration where one intent raised a tool error while another succeeded.
- **BaseException** "benign shutdown": Logged in [`vulnclaw/mcp/lifecycle.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/lifecycle.py) at line 511 when the MCP service deliberately closes a stream.
- **KeyError: 'target'**: Inside `apply_target_state_to_agent` when the target string is `None` because `--target` was omitted.

Enable detailed debugging with the `--debug` flag to surface full stack traces. Inspect the per-intent log in `session.log` and adjust tool round limits if timeouts occur:

```bash
vulnclaw config set session.solve_max_tool_rounds 10

```

## Web UI Startup Problems

The FastAPI-based web interface in [`vulnclaw/web/app.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/web/app.py) binds to `127.0.0.1:7788` by default.

**"Port already in use"** (`OSError: [Errno 98]`) occurs when a previous process holds the port.

**"Web UI disabled"** (`RuntimeError: Web dependencies not installed`) appears when `vulnclaw[web]` extras are missing, meaning FastAPI or uvicorn are not present as defined in [`setup.cfg`](https://github.com/Unclecheng-li/VulnClaw/blob/main/setup.cfg).

**"Remote access blocked"** prevents binding to `0.0.0.0` without the `--allow-remote` security flag.

Fix these with:

```bash

# Install web dependencies

pip install 'vulnclaw[web]'

# Use alternative port

vulnclaw web --port 8081

# Allow remote access (trusted networks only)

vulnclaw web --host 0.0.0.0 --allow-remote

```

Kill stale processes if needed:

```bash
lsof -i:7788
kill -9 <PID>

```

## Docker Permission Issues

Containerized deployments often encounter permission denied errors when accessing the Docker daemon or environment variables.

**"docker: permission denied"** occurs when the container cannot reach the host's Docker daemon socket.

**"VULNCLAW_LLM_API_KEY not set"** happens when the `.env` file is not mounted into the container.

Run with proper volume mounts and environment variables:

```bash
docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $HOME/.vulnclaw:/data \
  -e VULNCLAW_LLM_API_KEY=sk-xxxx \
  vulnclaw:latest bash

```

Alternatively, use the provided [`docker-compose.yml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/docker-compose.yml) which handles socket binding and environment variables automatically.

## Debugging Checklist

Follow this systematic approach to resolve VulnClaw errors:

1. Run `vulnclaw doctor` to verify Python version, LLM configuration, and MCP status.
2. Check `~/.vulnclaw/config.yaml` for missing keys like `llm.api_key` and `mcp.servers.*.enabled`.
3. Inspect `~/.vulnclaw/sessions/` for corrupted or missing snapshot files.
4. Enable verbose mode with `--debug` or `VULNCLAW_LOG_LEVEL=DEBUG`.
5. Test HTTP endpoints directly with `curl` to rule out network blocks.
6. Review `session.log` for exact exception line numbers.
7. Reinitialize with `vulnclaw init` after clearing old sessions.
8. Verify external binaries are executable (`which npx`, `java -jar`).

## Summary

- **Configuration errors** (API keys, Python version) validate in [`vulnclaw/web/app.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/web/app.py) and require environment variable checks or `vulnclaw doctor`.
- **MCP service failures** (fetch, Chrome, Burp) originate in [`vulnclaw/mcp/registry.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/registry.py) and require enabling services in config and installing external binaries.
- **Snapshot errors** (task not found, restore failed) indicate missing files in `~/.vulnclaw/sessions/` or mismatched target names.
- **Permission errors** (403, constraints) require checking LLM quotas or relaxing session constraints in [`vulnclaw/agent/solver.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/agent/solver.py).
- **Runtime exceptions** in [`vulnclaw/orchestrator.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/orchestrator.py) often resolve by increasing `solve_max_tool_rounds` or debugging with `--debug`.
- **Web UI issues** require installing `[web]` extras and managing port bindings.
- **Docker issues** require mounting the Docker socket and passing environment variables.

## Frequently Asked Questions

### What does "Task not found" mean in VulnClaw?

This error indicates the provided task ID does not exist in the current session cache. According to [`vulnclaw/web/app.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/web/app.py) at line 117, the system raises an `HTTPException(status_code=404)` after querying [`task_manager.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/task_manager.py). Verify active tasks with `vulnclaw task list` and ensure you are using the correct session context.

### How do I fix the "fetch service not enabled" error?

The fetch MCP service is disabled by default or the `npx` binary is unavailable. As implemented in [`vulnclaw/mcp/registry.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/registry.py), the registry raises `HTTPException(status_code=503)` when the service is not registered. Enable it by running `vulnclaw config set mcp.servers.fetch.enabled true` and ensure Node.js/npm is installed to access `npx`.

### Why am I seeing "Chrome not reachable" when using the Chrome DevTools MCP?

This error occurs when Chrome is not running on the expected remote-debugging port or the MCP command path is misconfigured. The lifecycle manager in [`vulnclaw/mcp/lifecycle.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/lifecycle.py) detects this as a connection failure. Start Chrome with `google-chrome --remote-debugging-port=9222` before enabling the service in VulnClaw configuration.

### How do I resolve Docker permission denied errors in VulnClaw?

Docker permission errors happen when the container cannot access the host's Docker daemon socket. Mount the socket with `-v /var/run/docker.sock:/var/run/docker.sock` and ensure the container user has docker group rights. Also verify that `VULNCLAW_LLM_API_KEY` is passed as an environment variable or mounted via `.env` file.