Troubleshooting Setup

LinuxmacOSWindowsFreeBSD

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 debug

A foreground daemon logs to your terminal. Follow the installed service's logs with:

journalctl -u scanopy-daemon -f

To capture logs to a file for sharing with support:

./scanopy-daemon --log-level debug 2>&1 | tee ~/scanopy-daemon.log

For 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/health

Solutions:

1. Verify server URL: Ensure SCANOPY_SERVER_URL is correct and reachable from the daemon host
2. Check the API key: Confirm the daemon's config.json holds the key from its install artifact. A daemon rejected with daemon_not_provisioned was installed by hand against a record that doesn't exist — create it in the UI and use the artifact that produces. See Daemon Identity.
3. 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 from raw.githubusercontent.com and binaries from github.com.
• Scanopy Cloud and commercial self-hosted pull images from docker.scanopy.net, and compose files and binaries from get.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 Scanopy Cloud or commercial self-hosted, you can also pull from GitHub directly. In your compose file, change docker.scanopy.net to ghcr.io in each image: line and keep the rest of the path, then run docker compose pull && docker compose up -d:

  image: ghcr.io/scanopy/scanopy/daemon:latest

  Download compose files from https://raw.githubusercontent.com/scanopy/scanopy/refs/heads/main/ and binaries from https://github.com/scanopy/scanopy/releases/latest/download/ instead of get.scanopy.net.

Getting Help

If your issue isn't covered here:

• Discord: Join our Discord community
• GitHub Issues: Open an issue