Troubleshooting Setup
Troubleshooting issues getting the Scanopy daemon running.
Issues getting the daemon connected and running. For problems that occur during scans, see Troubleshooting Scans.
Checking Daemon Logs
Symptoms: Daemon appears to start but nothing happens, scans don't run, or you need to share logs with support
First, run the daemon in the foreground with debug logging for more detail:
scanopy-daemon --log-level debugA foreground daemon logs to your terminal. Follow the installed service's logs with:
journalctl -u scanopy-daemon -fTo capture logs to a file for sharing with support:
./scanopy-daemon --log-level debug 2>&1 | tee ~/scanopy-daemon.logFor full details on log levels and output destinations, see Logging.
Daemon Not Connecting to Server
Symptoms: Daemon shows as offline in the UI, or logs show connection errors
Diagnosis: Test connectivity to the server from the daemon host:
curl https://your-server-url/api/healthSolutions:
- Verify server URL: Ensure
SCANOPY_SERVER_URLis correct and reachable from the daemon host - Check the API key: Confirm the daemon's
config.jsonholds the key from its install artifact. A daemon rejected withdaemon_not_provisionedwas installed by hand against a record that doesn't exist — create it in the UI and use the artifact that produces. See Daemon Identity. - Firewall rules: Ensure outbound HTTPS (port 443) is allowed from the daemon host.
Daemon Stops When Terminal Closes
Symptoms: Daemon runs in foreground and stops when SSH session or terminal window ends
Solution: Install the daemon as a background service with scanopy-daemon install … so it runs independently of your terminal session and survives reboots. See Running as a Service.
Docker Pull or Download Fails
Symptoms: docker compose pull, or curl of a compose file or server binary, fails with no such host, connection refused or a certificate error.
Cause: A DNS blocker such as Pi-hole or AdGuard Home, or a firewall, blocks a host Scanopy downloads from, or that host is down. The hosts depend on the edition:
- Community Edition pulls images from
ghcr.io, compose files fromraw.githubusercontent.comand binaries fromgithub.com. - Scanopy Cloud and commercial self-hosted pull images from
docker.scanopy.net, and compose files and binaries fromget.scanopy.net.
Solution:
-
Allow the hosts for your edition in your DNS blocker or firewall. For Scanopy Cloud and commercial self-hosted, also allow
*.scarf.sh. -
On commercial self-hosted v0.19.5 or later, set
SCANOPY_DISABLE_DOWNLOAD_GATEWAY=trueon the server and restart it. The daemon install and upgrade commands it generates then download from GitHub andghcr.io. -
On Scanopy Cloud or commercial self-hosted, you can also pull from GitHub directly. In your compose file, change
docker.scanopy.nettoghcr.ioin eachimage:line and keep the rest of the path, then rundocker compose pull && docker compose up -d:image: ghcr.io/scanopy/scanopy/daemon:latestDownload compose files from
https://raw.githubusercontent.com/scanopy/scanopy/refs/heads/main/and binaries fromhttps://github.com/scanopy/scanopy/releases/latest/download/instead ofget.scanopy.net.
"Too Many Open Files" Error
Symptoms: A run shows the warning File-descriptor limit slowed the deep scan or Port scan ran out of file descriptors, or fails with The scan ran out of file descriptors (too many open files).
Cause: The daemon's file descriptor limit is too low. Deep scanning a single host needs a few hundred descriptors, so a low limit forces concurrency down — sometimes to one host at a time.
The daemon raises its own soft limit at startup, up to the hard limit and capped at 10,240.
If you still see this, the hard limit is what needs raising.
Solutions:
-
Check what the daemon actually has. For the service:
systemctl show scanopy-daemon -p LimitNOFILEFor a daemon you run yourself, check the shell you start it from:
ulimit -Hn # hard limit — the ceiling the daemon can raise itself to ulimit -n # current soft limit -
Raise the hard limit. For the service, add an override with
sudo systemctl edit scanopy-daemon:[Service] LimitNOFILE=65535Then restart the service. For a daemon you run yourself, add to
/etc/security/limits.conf, then log out and back in:* soft nofile 65535 * hard nofile 65535
Getting Help
If your issue isn't covered here:
- Discord: Join our Discord community
- GitHub Issues: Open an issue
Product names and logos are trademarks of their respective owners. See credits.