Troubleshooting

📖 Canonical version: read this page on the official docs site — https://www.redamon.org/docs/troubleshooting. The GitHub wiki is a mirror.

Troubleshooting

Common issues and their solutions when running RedAmon.

---

Operating System Compatibility

RedAmon is fully Dockerized and runs on any OS that supports Docker and Docker Compose v2+. Below are common OS-specific issues and their fixes.

Linux

Problem	Cause	Fix
Docker socket permission denied	User not in docker group	sudo usermod -aG docker $USER then log out and back in
docker compose not found	Old Docker version uses docker-compose (hyphen)	Install Docker Compose V2 plugin or use docker-compose
Port already in use (3000, 8010, etc.)	Another service occupies the port	Change ports in .env or stop the conflicting service
Containers killed (OOM)	Insufficient RAM	Increase swap or free memory — see minimum requirements
Volume mount denied (SELinux)	Fedora / RHEL / CentOS enforce SELinux	Add :z suffix to volume mounts in docker-compose.yml, or run sudo setsebool -P container_manage_cgroup on
Firewall blocks container traffic	firewalld or ufw blocking Docker bridge	sudo ufw allow in on docker0 or allow the Docker subnet in firewalld
DNS fails inside containers	systemd-resolved conflicts (Ubuntu 22.04+)	Add {"dns": ["8.8.8.8", "8.8.4.4"]} to /etc/docker/daemon.json and restart Docker
/var/run/docker.sock not found	Docker not running or rootless Docker uses a different path	sudo systemctl start docker or set DOCKER_HOST to the correct socket path

Windows

Problem	Cause	Fix
Docker socket unavailable	Windows uses named pipes, not Unix sockets	Use Docker Desktop with WSL2 backend enabled
Line ending errors (\r\n)	Git auto-converts LF → CRLF on Windows	git config --global core.autocrlf input then re-clone the repo
Path too long errors	Windows 260-character path limit	git config --global core.longpaths true
Volume mount fails	Windows path format incompatible with Linux containers	Run from inside WSL2 filesystem (~/redamon), not from /mnt/c/
Extremely slow performance	Bind mounts across Windows ↔ WSL boundary	Store the project inside WSL2 home (~/), not on a Windows-mounted drive
Docker Desktop won't start	WSL2 or Hyper-V not enabled	Run wsl --install in PowerShell (admin), reboot, then install Docker Desktop
Socket permission error in WSL2	Docker Desktop integration not enabled for your WSL distro	Docker Desktop → Settings → Resources → WSL Integration → enable your distro

macOS

Problem	Cause	Fix
Slow bind-mount performance	macOS filesystem sharing overhead	Upgrade to Docker Desktop 4.x+ and enable VirtioFS in Settings → General
Port 5000 conflict	macOS AirPlay Receiver uses port 5000	Disable AirPlay Receiver in System Settings → General → AirDrop & Handoff, or remap the port in .env
docker compose not found	Docker CLI plugins not in PATH	Run brew install docker-compose or reinstall Docker Desktop

---

Container Issues

Services won't start

Check the status of all containers:

docker compose ps

If a service is in "restarting" or "exited" state, check its logs:

docker compose logs <service-name>

Common services to check: webapp, agent, recon-orchestrator, neo4j, postgres

No admin prompt at install / can't log in

The installer prompts you to create an admin account once the webapp is up. On a heavy first boot (especially --gvm, or a small VM) the webapp can take a while to start, so the automatic prompt may be skipped and you are left with no way to log in.

Create the admin at any time once the stack is running:

./redamon.sh status        # confirm the webapp is up
./redamon.sh create-admin  # waits for the webapp, then prompts for name/email/password

create-admin is safe to re-run: it upserts on email, so reusing an existing admin's email resets that password, while a new email adds another admin. Use it (not reset-password) when no admin exists yet: reset-password only updates a user that already exists.

Out of memory

RedAmon with the full GVM stack requires significant resources. If containers are being killed:

1. Check Docker's memory allocation (Docker Desktop > Settings > Resources)
2. Increase to at least 8 GB RAM (16 GB recommended for GVM)
3. Or run without GVM for a lighter footprint:

   ./redamon.sh install        # Production (first time)
   ./redamon.sh up             # Subsequent starts

Build killed with exit 137 / Killed. If install or update dies while building images (usually during the webapp build), the host ran out of memory building multiple images at once. RedAmon already builds the RAM-heavy webapp image on its own and auto-caps build parallelism from the memory reported by docker info. On a tight machine you can force it lower:

REDAMON_BUILD_PARALLEL=1 ./redamon.sh update   # build one image at a time

Set REDAMON_BUILD_PARALLEL=0 to disable the cap (unbounded). On macOS/Windows, raising Docker Desktop's memory (Settings > Resources) also helps; on Linux, adding swap does.

KB build/refresh skips one feed ("sha256 does not match pinned")

RedAmon pins each knowledge-base feed to a fixed upstream commit and verifies it before ingesting. On a mismatch it skips only that feed and keeps the existing corpus intact, then continues. This usually means the upstream source changed and the pin has not been bumped yet; rerun once the pin is updated (services/knowledge_base/curation/pins.py). A wrong model pin can instead make docker compose build agent fail while fetching the pinned embedder/reranker revision. Likewise, an image build that fails on a go install ...@<sha> or a wordlist download is a pinned build artifact that moved - restore/bump the pin and rebuild.

Internal service calls return 401 after enabling INTERNAL_KEY_ALLOWLIST_ENFORCE

By default the internal service key is accepted only on its known routes in log-only mode (nothing is blocked). If you set INTERNAL_KEY_ALLOWLIST_ENFORCE=true and a service starts failing with 401, an internal call hit a route outside the allowlist. Check the webapp logs for [internal-key] BLOCKED off-allowlist lines, then unset the variable (back to log-only) until that route is expected.

Port conflicts

If a port is already in use on your host:

# Check what's using port 3000
lsof -i :3000

You can change ports in .env:

WEBAPP_PORT=3001
NEO4J_HTTP_PORT=7475
POSTGRES_PORT=5433

---

GVM / OpenVAS Issues

GVM takes forever on first start

The first GVM startup requires a ~30 minute feed synchronization to download 170,000+ NVTs. This is normal and only happens once.

Monitor progress:

docker compose logs -f gvmd

GVM scan button is disabled

The GVM scan button requires:

• Reconnaissance must have completed for the project (GVM needs IP/hostname data)
• The GVM stack must be running
• Stealth mode must be disabled (GVM generates active probes)

GVM credentials

Default: admin / admin (auto-created on first start)

To change:

docker compose exec -u gvmd gvmd gvmd --user=admin --new-password='<new-password>'

---

AI Agent Issues

Agent not connecting

Check the WebSocket connection indicator in the AI Agent drawer:

• Green WiFi icon = connected
• Red WiFi icon = disconnected

If disconnected:

1. Check the agent container is running: docker compose ps agent
2. Check agent logs: docker compose logs -f agent
3. Try refreshing the page
4. Restart the agent: docker compose restart agent

Agent not responding

If the agent seems stuck:

1. Click Stop to halt the current operation
2. Check agent logs for errors: docker compose logs -f agent
3. Click Resume to continue, or start a new conversation

"An agent session is running", but none is

Activating a version, dispatching a queued full recon, and applying a preset or changing a target list over MCP all wait while an agent session is running on the project, because they would change or wipe the graph under it. RedAmon asks the agent which sessions it is really running, so a session left marked as running by an agent that restarted mid-run is cleared the next time one of these checks runs, and stops blocking.

If the message says an agent session is marked running and the agent could not be reached to confirm it, the agent container is down or not answering:

1. Check it: docker compose ps agent
2. Read its logs: docker compose logs --tail=100 agent
3. Start it again with ./redamon.sh up, then retry.

Model not available

If the model selector shows no models or specific providers are missing:

1. Check that API keys are set correctly in .env
2. Restart the agent container: docker compose restart agent
3. Check agent logs for API key errors: docker compose logs agent | grep -i "error\|key\|auth"

A feature asks for a model, or says its model could not be used

Triage review, CodeFix, Multi mute, report narratives, RoE parsing, the recon preset generator, the command whisperer and the Tradecraft section picker each run on their own model, set once per account in Global Settings → LLM Providers → Models by feature. A feature with none asks the first time you use it.

• Your model X could not be used: the provider refused that model or key, or the provider was deleted. Choose another model in the picker that opens, or fix the provider. The provider's own error is in docker compose logs agent, with keys redacted.
• The agent is older than the webapp: rebuild it: the agent and webapp images come from different versions. Rebuild both (./redamon.sh update).
• The agent failed while handling this request: an error inside the agent, not a version mismatch. The traceback is in docker compose logs agent.
• The project owner's model settings could not be loaded (Triage review, CodeFix): the agent could not read the owner's settings or LLM providers from the webapp, so it did not start. Nothing was changed, and your model is still set: try again. If it keeps happening, docker compose logs agent | grep "Failed to fetch user providers" shows why.

---

Reconnaissance Issues

Recon scan hangs

If the reconnaissance scan appears stuck:

1. Check the recon orchestrator logs: docker compose logs -f recon-orchestrator
2. Check if the recon container is running: docker compose ps
3. Some phases (especially Nuclei and Katana) can take a long time on large targets

No nodes appearing in graph

After running recon, if the graph is empty:

1. Verify the target domain is accessible
2. Check the recon JSON output exists: ls recon/output/
3. Verify "Update Graph Database" is enabled in project settings
4. Check Neo4j is running: docker compose logs neo4j

---

Database Issues

PostgreSQL connection errors

docker compose logs postgres

If corrupt or needs reset:

docker compose down
docker volume rm redamon_postgres_data
docker compose up -d

Warning: This deletes all users, projects, and settings.

Neo4j connection errors

docker compose logs neo4j

Verify the password in .env matches what Neo4j expects. If Neo4j was initialized with a different password, you may need to reset the volume:

docker compose down
docker volume rm redamon_neo4j_data
docker compose up -d

Warning: This deletes all graph data (recon results, exploit records, etc.).

---

Python Service Changes Not Taking Effect

Python services (agent, recon-orchestrator, kali-sandbox) have source code volume-mounted but cache modules at import time. After modifying .py files:

docker compose restart agent              # AI agent
docker compose restart recon-orchestrator  # Recon orchestrator
docker compose restart kali-sandbox       # MCP tool servers

---

Webapp Not Reflecting Changes

For the Next.js webapp in production mode, you need to rebuild:

docker compose build webapp
docker compose up -d webapp

For development mode (hot-reload), create the override file first:

cp docker-compose.dev.yml docker-compose.override.yml
docker compose up -d

---

Full Reset

To completely reset RedAmon and start fresh:

# Remove containers + images, keep data
./redamon.sh clean

# Remove EVERYTHING including all data
./redamon.sh purge

Then reinstall:

./redamon.sh install            # Without GVM
./redamon.sh install --gvm      # With GVM

Warning: purge destroys ALL data -- users, projects, graph data, scan results, and conversations.

---

Getting Help

• GitHub Issues: github.com/samugit83/redamon/issues — report bugs or request features
• Service logs: docker compose logs -f <service> — always check logs first
• Docker status: docker compose ps — verify all containers are healthy