Troubleshooting

Full troubleshooting guide: Wiki — Troubleshooting

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
Containers OOM-killed during install	Docker Desktop default Memory below RedAmon minimum	Docker Desktop → Settings → Resources → Memory: set to 4 GB (8 GB with --gvm), then ./redamon.sh install
Cannot connect to the Docker daemon	Docker Desktop not started	open /Applications/Docker.app and wait until the whale icon stops animating before running ./redamon.sh
Mounts denied / path not shared	Repo cloned outside Docker Desktop's File Sharing allowlist	Clone the repo under ~/ (default-allowed), or add the custom path in Settings → Resources → File Sharing
SYN scans (naabu, masscan) miss hosts on the local LAN	network_mode: host joins Docker Desktop's LinuxKit VM, not the Mac's network	Expected on Docker Desktop. Internet targets work normally; for LAN scans, run RedAmon on a Linux host
Login fails after install with no error in logs	Non-interactive shell (CI, agents, some multiplexers) injected a \u0001 SOH byte into the admin email/password prompt	Run ./redamon.sh create-admin to (re)create the admin cleanly (reset-password only works once an admin already exists)
No admin prompt appeared at install / can't log in	Webapp was slow to come up on first boot (common with --gvm or a small VM), so the automatic admin prompt was skipped	Run ./redamon.sh create-admin once the stack is up (./redamon.sh status); it waits for the webapp, then prompts. Safe to re-run

---

The graph page hangs, 502s, or Neo4j logs "network aborts"

These three symptoms usually appear together on a project with a very large graph. They have distinct causes, so check them in this order.

Symptom	Cause	Fix
Neo4j logs Increase in network aborts detected, connection count climbs steadily	Fixed in this release. The webapp used to create a new Neo4j driver (and a new pool of up to 50 Bolt connections) on every production request, abandoning the previous one	Update. Confirm with CALL dbms.listConnections() — the count must stay flat while you reload the graph page, not climb
API requests sit in [pending] forever, no error, no timeout	Fixed in this release. The driver's connection timeouts only bound acquiring a connection, so an unbounded whole-graph query ran forever	Update. Tune with NEO4J_QUERY_TIMEOUT_MS (default 120000) if you legitimately run long analytical queries
HTTP 502 from nginx, recv() failed (104: Connection reset by peer) in its error log	The webapp container was OOM-killed mid-response. A reset with no timeout means the process died, rather than the request being slow	Check ./redamon.sh status for OOM-killed containers and restart counts. Memory limits are sized from host RAM automatically; see README.MEMORY_GOVERNOR.md
Containers OOM-killed generally	Host genuinely too small, or limits pinned by hand in .env	./redamon.sh status shows the computed allocation and warns when a running container has drifted from it

Useful checks:

./redamon.sh status                                    # OOM kills, restarts, allocation, disk
docker logs redamon-neo4j --tail 50 | grep -i abort    # Bolt connection aborts
docker inspect redamon-webapp --format '{{.RestartCount}} {{.State.OOMKilled}}'

---

./redamon.sh update refuses to pull

RedAmon's own scans used to dirty the git checkout. recon/ is bind mounted read-write into the spawned recon container, and two of its git-tracked data directories are re-downloaded there whenever their 24h cache expires:

Path	Written by	Contents
recon/main_recon_modules/data/mitre_db/	add_mitre.py	MITRE CVE/CAPEC/CWE database, 15 files
recon/main_recon_modules/data/wappalyzer_cache/	http_probe.py	Wappalyzer fingerprints, technologies.json

So after a scan or two git pull --ff-only refused, and the error advised git commit -am 'local changes', which converts a self-healing dirty tree into a permanent dead end: the checkout then has a commit the project does not and a fast-forward can never happen again (issue #185).

update now restores both directories before pulling. Never commit files under them; they are machine-local caches that every scan may rewrite.

Symptom	Cause	Fix
Could not pull updates: the working tree has local changes with no file list under it, and git status is clean	Not local changes at all: the branch has diverged. git log --oneline origin/master..HEAD shows a local changes commit	Update once from a version that has this fixed. If you are already stuck, see the one-time recovery below
Same error, with a list of modified files under recon/main_recon_modules/data/	Fixed in this release. update restored only a .last_update marker that had since been gitignored, so it was doing nothing while the database directories beside it were what actually drifted	Update. Never commit those files — they are re-downloaded on every scan
Permission denied writing .torch-variant, .git/index, or similar	An earlier sudo ./redamon.sh … or sudo git … left root-owned files in a user-owned checkout	sudo chown -R "$(id -un):$(id -gn)" ., then re-run without sudo. update now checks this up front rather than failing halfway
Could not pull updates. plus a NOTE: 'git status' failed here block	Another git process (an IDE, a hook, an interrupted command) holds .git/index.lock, or the index is corrupt. update deliberately refuses to auto-recover while it cannot read your working tree	Wait for the other git process to finish, or remove a stale .git/index.lock only if none is running. Do not reset --hard until git status works — it would discard uncommitted work nobody can see
error: unable to unlink … Permission denied on a file under recon/main_recon_modules/data/	The scan container creates those cache directories as root inside a user-owned checkout, so neither git nor you can replace the file	Same chown. update now warns about root-owned runtime files before a release that changes one makes the pull fail

One-time recovery if your checkout has already diverged. The fix ships inside redamon.sh, which is the file you cannot pull, so a checkout that is already in this state needs one manual reset. It discards the bogus local changes commit only; run git log --oneline origin/master..HEAD first and copy anything of your own onto a branch if that list contains real work.

cd ~/redamon
sudo chown -R "$(id -un):$(id -gn)" .   # only if an earlier run used sudo
git fetch origin
git reset --hard origin/master
./redamon.sh update

From that release on, update recovers by itself: a diverging commit whose files are all RedAmon runtime files is reset automatically and reported, while a commit touching anything else stops the update with instructions that keep your work.

The automatic reset is the only destructive step in update, and it is gated four ways: the working tree must be clean, git status must be readable, every file in the diverging commits must sit under a RedAmon runtime data directory, and no path may contain a traversal. To disable it entirely and always recover by hand, set REDAMON_NO_AUTO_RESET=1.