Troubleshooting

Common issues and solutions for self-hosted Scanopy server deployments.

For daemon-related issues, see Daemon Troubleshooting.

Server Issues

Port Already in Use

Symptoms: Server fails to start with "address already in use"

Solution: Change the port mapping in docker-compose.yml:

ports:
  - '8080:60072' # Change 60072 to any available port

Browser Shows "SSL Protocol Error"

Symptoms: Browser displays "ERR_SSL_PROTOCOL_ERROR" when accessing Scanopy

Cause: Using https:// instead of http://. Scanopy doesn't handle TLS directly.

http://your-server:60072

Solution: Use http:// to access Scanopy directly. For HTTPS, put a reverse proxy (Traefik, Nginx, Caddy) in front to handle TLS termination.

Web UI Doesn't Load, but the API Responds

Symptoms: The server address returns a 404 in the browser, while curl http://your-server:60072/api/health succeeds. The startup log shows Web UI: disabled (API-only), followed by a warning that names the cause.

Cause: The server has no web UI to serve. The binary was compiled from source without the UI, and SCANOPY_WEB_EXTERNAL_PATH is either unset or points at a directory with no index.html. The release binary and the Docker image both include the UI.

Diagnosis: Read the startup log:

journalctl -u scanopy-server | grep -A1 "Web UI"

To check whether a binary has the UI compiled in:

grep -a -c __sveltekit_ /path/to/scanopy-server

0 means it has none.

Solution: Replace the binary with the release build, as in Upgrading a native install. It serves the UI with no extra configuration. To build from source instead, build the UI first, then compile the server with cargo build --release --bin server --features embed-ui.

PostgreSQL "Could not create any Unix-domain sockets" (Proxmox)

Symptoms: PostgreSQL container fails to start on Proxmox host with socket creation error

Cause: AppArmor security policy blocking socket creation.

Solution: Add to both PostgreSQL and Scanopy services in docker-compose.yml:

security_opt:
  - apparmor:unconfined

See issue #87 for details.

Integrated Daemon Not Initializing

Symptoms: Integrated daemon shows in UI but doesn't start discovery

Diagnosis:

# Check daemon logs
docker logs scanopy-daemon

# Check if daemon can reach server
docker exec scanopy-daemon curl http://scanopy-server:60072/api/health

Solutions:

Verify bridge network: Check your Docker bridge IP

docker network inspect bridge | grep Gateway

Update compose file: If gateway isn't 172.17.0.1, update SCANOPY_INTEGRATED_DAEMON_URL
Check the daemon record: Server setup provisions the integrated daemon and its API key. Confirm the daemon appears in Discover > Scan > Daemons and that its daemon-config volume still holds the key — a wiped volume leaves the daemon with no identity to present.

Emails Aren't Being Sent

Symptoms: Password reset, invite, or install-command emails never arrive. The UI reports only that Scanopy could not send the email and asks you to check the server logs — the mail server's own reply is deliberately kept out of the interface.

Diagnosis: The server logs the mail server's reply, with its reply code and whether the failure was TLS or a timeout.

docker logs scanopy-server 2>&1 | grep -i smtp

Check the log from startup as well. A partial SMTP configuration, or a relay the server could not build a transport for, disables email and says so at boot.

Solutions:

Fill in every SMTP setting: relay, username, password, and sender email must all be set together. With any of them missing, email stays disabled. See SMTP Configuration.
Check the port: SCANOPY_SMTP_PORT defaults to 465, which is implicit TLS. Providers that accept authenticated submission only on 587 with STARTTLS — Microsoft 365 among them — do not listen on 465, and the connection fails before authentication.
Confirm the settings reach the container: the published docker-compose.yml passes a .env beside it through to the server. In a compose file of your own, the server service needs its own env_file entry, or the variables set under environment.

Database Issues

How to Backup Data

Scanopy stores all data in PostgreSQL. To backup:

Docker setup:

# Backup
docker exec scanopy-db pg_dump -U postgres scanopy > scanopy_backup.sql

# Restore
docker exec -i scanopy-db psql -U postgres scanopy < scanopy_backup.sql

Manual setup: Use standard PostgreSQL backup tools (pg_dump, pg_restore).

How to Reset Password

If SMTP is configured, use the "Forgot Password" link on the login page.

If SMTP is not configured:

Generate a new password hash using bcrypt
Update the users table with the new hash
Or, ask another Owner to delete and re-invite you

How to Delete All Data

To start fresh:

docker compose down -v  # Removes all volumes including database
docker compose up -d    # Start fresh

Reverse Proxy Setup

Configure your reverse proxy (Nginx, Traefik, Caddy) to forward traffic to port 60072. Forward every path, not only /api: the server also serves the web UI and share links.

For HTTPS, enable secure cookies in docker-compose.yml:

environment:
  - SCANOPY_USE_SECURE_SESSION_COOKIES=true

See Server Configuration for details.

Getting Help

If your issue isn't covered here:

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

On this page