Troubleshooting
Diagnose common authentication, database, scanner, and browser failures.
Protected endpoints return 401
Confirm the token is current, uses the right scope, and targets the intended organization. For browser sessions, sign out and sign in again after identity-provider changes.
Frontend or browser cannot reach the backend
Verify allow_origins includes the public application URL, reverse proxy routes /api to the backend, and the browser is using the same scheme and host expected by OIDC.
Scans remain pending or stale
Open the scan's Process Center entry and compare its state and phase with the scan detail. Queued means the request was accepted but no worker has claimed it; running means a worker is active; failed means execution stopped with an error; and cancelled means an operator stopped it. A phase without a percentage is expected when the scanner has no meaningful total. Inspect backend logs and scanner health, then check registry access, available worker capacity, command timeout settings, and vulnerability database refreshes. After a backend restart, allow the durable recovery pass to requeue pending work before treating a queued scan as lost.
If the scan was deleted, its linked Process Center entry is deleted with it. Process Center records are operational history; the scan record remains the source of truth for findings, SBOM data, and the release/policy verdict. There is no Process Center retry action: address the recorded execution error and submit a fresh scan. A policy failure is not a scanner retry condition.
CVE Intelligence sync is slow or failing
Open CVE Intelligence and inspect the active phase, completed/total events, unique CVEs, current CVE, last progress update, checkpoint error, and recent sync runs. The worker follows a resumable change cursor and only advances it after successful enrichment and posture evaluation. A large initial lookback or many distinct changed CVEs can take a long time because upstream requests are deliberately rate-limited. A database-column error indicates an incomplete or mismatched backend migration; stop repeated retries, resolve the migration state, and restart the backend before running the worker again.
Registry credentials do not save
Check the encryption key and backend logs. Do not rotate the key without a migration plan for existing encrypted credentials.
OIDC login returns to an error or does not grant access
Compare the provider callback URL with the exact HTTPS URL used by the deployed backend, then confirm allow_origins contains the public application URL. Check the configured scopes and claim mappings, and sign out before retesting changed group or role membership. Keep a tested administrator recovery route before disabling local authentication.
Xray scan cannot start or returns incomplete data
Confirm the registry's Xray mode and credentials match the intended behavior. Limited mode reads an existing result after warming through Artifactory; full mode needs Xray Read and Manage Xray Metadata to request a fresh scan. Inspect the scan step and backend logs before retrying.
Notifications do not arrive
Test the configured channel, inspect notification delivery logs and queued jobs in the same user or organization scope, and verify the destination's credentials and network reachability. For callbacks, confirm the target is public HTTPS or explicitly allowlisted and that it does not rely on redirects.
Upgrade or restore does not recover registry access
Confirm the restored deployment uses the same encryption key that protected the original registry credentials. Restore PostgreSQL first, then the backend data volume where applicable, start the backend, verify health, and test one non-production registry before reopening CI gates.