ScanopyScanopy

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 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 commercial self-hosted v0.19.5 or later, set SCANOPY_DISABLE_DOWNLOAD_GATEWAY=true on the server and restart it. The daemon install and upgrade commands it generates then download from GitHub and ghcr.io.

  • 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.

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

  1. Check what the daemon actually has. For the service:

    systemctl show scanopy-daemon -p LimitNOFILE

    For 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
  2. Raise the hard limit. For the service, add an override with sudo systemctl edit scanopy-daemon:

    [Service]
    LimitNOFILE=65535

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

Product names and logos are trademarks of their respective owners. See credits.

On this page