Troubleshooting

Most "something is broken" reports turn out to be an honest empty state doing its job. Before anything else, ask three questions in this order:

1. 1Has a scan run? RelixQ renders only real signals. A project with zero scans has nothing honest to show.
2. 2Is the connector configured? Export destinations, TLS ingest, and the event pipeline are all config-gated and will look connected while delivering nothing.

Dashboards empty right after first login

Why: no scans have run yet — dashboards render only real signals, never placeholder numbers. Fix: connect a repository and trigger a scan, or submit local CLI results with relixq submit.

Score reads "Not yet assessed"

Why: there is not enough scan coverage to compute an honest score, so the product refuses to show one. An unmeasured estate scoring 90 would be a lie. Fix: run or widen scan coverage.

"Inventory not available in this deployment"

Why: the web app cannot reach a backend serving the inventory routes. This is an honest capability signal, not a data bug. Fix: raise it with your tenant administrator — you should not see this on a fully provisioned tenant.

TLS endpoints and certificates tables are empty

Why: the read API is live, but nothing populates it until a TLS scan or ingest connector has run. Fix: run relixq scan tls <host>, or have the TLS worker configured against your endpoints.

PQC lab says "No lab results yet"

Why: lab rows enter the platform only by ingesting real harness output. There is no built-in lab runner and no synthesized data. Fix: ingest a harness run via the lab ingest endpoint.

Blocking decisions and Policy violations read zero

Why: the policy-decision aggregates are honest-empty until gate decisions have actually been recorded. Fix: run the release gate against a pull request; the aggregates populate from real decisions.

Sign-in refused with a generic error, but the password is right

Why: the server distinguishes several conditions the UI shows generically — unverified email, account locked after 10 failures for 15 minutes, org-enforced SSO, or MFA enrolled (the web form does not yet present an MFA challenge). Fix: verify your email, wait out the lockout, use your identity provider, or complete MFA through the API.

You land on /no-access

Why: you are signed in but not a member of any organization. Fix: accept an invitation, or create your own organization.

An invitation link shows a mismatch warning

Why: you are signed in as a different email than the one invited. The server deliberately does not reveal org details to a mismatched viewer. Fix: switch account, or ask for an invitation to your current address.

The CLI says "not logged in" in CI

Why: CI runners usually have no OS keyring, so keychain lookup fails. Fix: set RELIXQ_API_TOKEN in the CI environment — it is checked before the keychain. Note that relixq pentest gate degrades to findings-only rather than failing in this case.

Scheduled scans are not firing

Why, in order of likelihood: the schedule is disabled, or its next-run time has not arrived — the scheduler ticks every 30 seconds. Fix: verify the schedule is enabled via GET /api/v1/projects/{projectId}/schedules. There is no web UI for schedules yet.

The PR gate does not block the merge

Why: relixq pr-comment always exits 0 on success, even in block mode. Enforcement is the check-run conclusion. Fix: add the RelixQ check to your branch-protection required status checks. If you want the CI step itself to fail, use relixq scan --exit-on or relixq pentest gate --mode block.

Every finding counts as new in the gate

Why: with no base SARIF supplied, every head finding is treated as new. Correct for a first scan, noisy for an old codebase. Fix: supply --base-findings-sarif, or commit a baseline file.

A scoped policy did not apply in CI

Why: CLI SARIF findings carry no environment or service scope, so a policy scoped to production services cannot match through the CLI gate. The condition detail says so explicitly. Fix: do not rely on scoped block policies in the CLI path; gate on severity and new-exposure conditions instead.

relixq pentest run --active is refused with 403

Why: active mode requires a signature-verified Rules of Engagement. There is no override flag, by design. Fix: author and sign the RoE. See QAST.

The gate says a condition is not_evaluated

Why: that condition needs backend data and no credential or remote was available — or, for asset-coverage-regression, no coverage endpoint exists yet and the gate refuses to fabricate one. not_evaluated always fails open. Fix: set RELIXQ_API_TOKEN to enable the backend conditions.

An App-triggered PR scan produced no PR comment

Why: the GitHub App does not write to your pull request today; all PR-surface output comes from the CLI in your own workflow. Fix: wire relixq pr-comment or relixq pentest gate into CI. See Release gates.

"AI is not configured" / explanation unavailable

Why: AI explanations are not enabled for your tenant. There is deliberately no canned fallback text — invented migration guidance would be worse than none. Fix: ask your account team to enable it. Note that some tenants run with external AI calls switched off by policy; if yours does, that is the answer rather than a fault.

Connected an export destination but no events arrive

Why, most commonly: the finding-event producer is not wired, so fan-out is a no-op and connections can be green and tested while zero events flow. Then: no completed scans; the wrong streams enabled; or the connection paused. Fix: work through those four in order — see Integrations.

Deliveries show failed then dead-letter

Why: failed rows are retriable attempts; dead-letter means the bounded retry budget was exhausted and the service gave up explicitly. Fix: dead-lettered batches are not replayed automatically — fix the destination (401/403 means credentials, 429 means quota) and new deliveries resume with the next event.

An alert fired once and never again

Why: that is dedup working as designed. Incidents are trigger-once / resolve-once, so a threshold breached across ten scans holds one open incident. Fix: nothing.

/policies and /exceptions say "Not yet implemented"

Why: those two pages are intentional stubs. The governance backend — policy engine, TTL-bounded exceptions, audit chain — exists and is reachable via the API and the CLI gate. Fix: use the API surface today.

Buttons on the finding detail page do nothing

Why: Request Exception, Create Ticket, and Assign Owner are deliberate stubs that announce they are not yet wired. Mark False Positive is fully wired. Fix: use the governance and ticketing APIs for the other three.