This guide covers common issues you may encounter when running Shannon and how to resolve them.
Repository Issues
Repository Not Found
Problem: Error message stating repository not found.
Solution: The REPO parameter must be a folder name inside ./repos/, not an absolute path. Clone or symlink your repository there first:
ln -s /path/to/repo ./repos/my-repo
Temporal Issues
Temporal Not Ready
Problem: Shannon fails to start with “Temporal not ready” error.
Solution: Wait for the health check to complete or check Temporal logs:
docker compose logs temporal
Worker Not Processing
Problem: Workflows are queued but not executing.
Solution: Check if all containers are running:
Ensure the worker container is healthy and running.
State and Data Issues
Reset State
Problem: Need to completely reset Shannon’s state and data.
Solution: Stop Shannon with full cleanup:
./shannon stop CLEAN=true
This will delete all workflow data, audit logs, and workspaces. Make sure to back up any reports you need.
Network Issues
Local Applications Unreachable
Problem: Shannon cannot connect to applications running on localhost.
Solution: Docker containers cannot reach localhost on your host machine. Use host.docker.internal instead:
./shannon start URL=http://host.docker.internal:3000 REPO=repo-name
PIPELINE_TESTING=true to skip external tools with graceful degradation:
./shannon start URL=https://example.com REPO=repo-name PIPELINE_TESTING=true
Container Permission Issues
Problem: Permission denied errors when running Docker commands or accessing output files.
Solution: On Linux, you may need to run commands with sudo depending on your Docker setup:
sudo ./shannon start URL=https://example.com REPO=repo-name
docker group:
sudo usermod -aG docker $USER
API and Authentication Issues
Rate Limiting
Problem: Hitting Anthropic API rate limits during testing.
Solution: If using Anthropic subscription plans with a rolling 5-hour window, add retry configuration to your config file:
pipeline:
retry_preset: subscription # Extends max backoff to 6h, 100 retries
max_concurrent_pipelines: 2 # Run 2 of 5 pipelines at a time
max_concurrent_pipelines setting (1-5, default: 5) controls how many vulnerability pipelines run simultaneously. Lower values reduce burst API usage but increase total runtime.
Authentication Errors
Problem: API key authentication fails.
Solution: Verify your API key is correctly set in the .env file:
cat .env | grep ANTHROPIC_API_KEY
Getting Help
If you encounter issues not covered here: