Troubleshooting

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

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:

   docker compose up -d postgres neo4j recon-orchestrator kali-sandbox agent webapp

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

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"

---

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

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

---

Full Reset

To completely reset RedAmon and start fresh:

# Stop everything, remove images and all data volumes
docker compose --profile tools down --rmi local --volumes --remove-orphans

Then rebuild and start:

docker compose --profile tools build
docker compose up -d

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