Troubleshooting#

1) UI/API returns 401#

Check:

• Forward auth header is injected correctly
• Anonymous dev mode is disabled/enabled as intended
• Proxy forwarding rules include supervisor paths when needed

2) Compose projects are not discovered#

Check:

• Compose labels are present on running containers
• config_files absolute paths are readable inside dockrev container
• Any Dockrev-generated override path is mounted consistently, such as self-upgrade.override.yml next to the configured absolute DOCKREV_SUPERVISOR_STATE_PATH, or /tmp/dockrev-override-<project>-<ulid>.yml
• Any user-managed extra compose / override file still exists and is mounted

If a service is stopped but every saved Compose file is readable and valid, discovery reports stopped instead of archiving it. Open the linked Stack and use the existing start action. Dockrev auto-archives only when every saved Compose file is absent. A partial absence, permission/I-O failure, or parse error stays visible as invalid; repair the file or mount and rerun discovery. A user archive is never removed by discovery.

3) Check jobs fail or run slowly#

Check:

• Registry rate limiting (429)
• Retry parameters are adequate
• Network connectivity and registry credentials

4) GHCR webhook does not trigger scan#

Check:

• Callback URL is publicly reachable over HTTPS
• Delivery reaches Dockrev
• X-Hub-Signature-256 validation passes
• Repo is selected in tracked repo list
• Queue shows matching check.service jobs; discovery is only the zero-match fallback

Immediate actions:

1. If the only unreadable file is a Dockrev-generated override file, such as self-upgrade.override.yml next to the absolute DOCKREV_SUPERVISOR_STATE_PATH shared by dockrev and supervisor, or /tmp/dockrev-override-<project>-<ulid>.yml, rerun discovery and let Dockrev fall back to the remaining readable compose files.
2. If the unreadable file is a user-managed compose/override file, fix the same-absolute-path mount first; discovery will keep the project invalid until that file is readable.
3. If webhook deliveries already return 200 but candidates stay stale, inspect the matched check.service job logs; digest-only image refs should now be accepted instead of failing as invalid image ref.

5) Self-upgrade button is disabled#

Check:

• /supervisor/self-upgrade reachability
• Forward auth header on supervisor routes
• Correct target image repo configuration

6) Job appears stuck in running state#

Check:

• Scope-level mutex conflicts with other jobs
• Startup recovery behavior after restart
• Per-job logs to identify blocking phase