13. Troubleshooting

Troubleshooting

Common issues and their solutions when running RedAmon.

---

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