How to Troubleshoot Common VulnClaw Errors: A Complete Guide

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 and 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, 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 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.

To resolve these issues:

# 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, 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 and 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 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 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:

# 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 and vulnclaw/target_state/store.py.

"Task not found" (HTTPException(status_code=404) at line 117 in vulnclaw/web/app.py) occurs when the task ID does not exist in the session cache managed by 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.

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:

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

4. List running tasks to verify IDs:

vulnclaw task list

5. If the cache is corrupted, reinitialize:

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) 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 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:

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 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 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:

vulnclaw config set session.solve_max_tool_rounds 10

Web UI Startup Problems

The FastAPI-based web interface in 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.

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

Fix these with:

# 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:

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:

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 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 and require environment variable checks or vulnclaw doctor.
• MCP service failures (fetch, Chrome, Burp) originate in 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.
• Runtime exceptions in 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 at line 117, the system raises an HTTPException(status_code=404) after querying 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}