Troubleshooting

Agents never check in (400 DisallowedHost)

Agents and background services reach the Reef server by its internal service name, web. Reef always trusts that name automatically. If you renamed the web service in your compose file, set REEF_INTERNAL_WEB_HOST to the new name. Otherwise, no agent can check in. See the Configuration reference.

For agents on other hosts, also confirm that:

• REEF_API_URL points to an address the host can reach.
• That address is listed in DJANGO_ALLOWED_HOSTS on the server.
• The agent’s REEF_AGENT_API_KEY matches one of the server’s DJANGO_API_KEYS.

“Bad Request (400)” when opening the dashboard

Add the IP address or hostname you’re using to DJANGO_ALLOWED_HOSTS and restart Reef. Each host listed there is automatically trusted for logins and other form submissions. If Reef sits behind a TLS-terminating proxy, also set DJANGO_TRUST_PROXY=true.

A scan stays “running” until it expires

The most common cause is a result too large for the server to accept. Grype results from large hosts are the usual example. Raise REEF_RAW_OUTPUT_MAX_BYTES well above the size of a typical result, then check the web container logs for RequestDataTooBig errors.

Also confirm that the scan isn’t simply slow. Full-host ClamAV sweeps and OpenSCAP scans on large systems can legitimately take hours.

Lynis or OpenSCAP reports on the container instead of the host

Check the scan summary. It shows which host and operating system were actually audited.

• Lynis always audits the host unless in_container is set or REEF_SCAN_ROOT=/.
• OpenSCAP is most accurate when openscap is installed on the host. Without it, older hosts (earlier than Fedora 36, RHEL 9, Ubuntu 22.04, or Debian 12) fall back to a limited, file-only mode. See OpenSCAP.

“database is locked”

Reef is configured to handle normal simultaneous activity without this error. If it still appears, the likely cause is an unusually long-running operation, such as a very large bulk update or a reset, holding the database. Wait for that operation to finish and try again. If the error persists, collect the web and worker logs and include them in a bug report.

Canceling a scan doesn’t stop it immediately

This is expected. The cancel reaches the agent on its next check-in, which happens about every 30 seconds during a scan. The agent then stops the scan and discards any partial results.

An agent shows offline during a long scan

This shouldn’t happen, because agents keep checking in while a scan runs and Reef never marks a scanning agent offline. If you see it anyway, the scan may have crashed the agent. Check the agent container logs, and confirm that the host has enough memory for REEF_SCAN_TMP_SIZE.

Where to look

• The web, worker, beat, and agent container logs (docker compose logs <service>)
• The Agents page, for check-in and offline status
• python manage.py sysinfo, for a quick environment summary (see Management Commands)
• A scan’s detail page, where the Raw output section shows exactly what the scan tool reported