Troubleshooting
Fix install, login, gate, and connector issues from the symptom.
Most issues come from a wrong OIDC redirect URI, missing gate token, connector scope mismatch, stale evidence, or a pipeline running local mode when server mode is required.
Invalid parameter: redirect_uri
Add the exact callback URL to the OIDC client: https://release-passport.example.com/releasepassport/v1/auth/callback.
Gate returns HOLD with missing evidence
Check connector scope, service name, namespace, source SHA, image digest, and rendered manifest path.
Console redirects to portal on releasepassport.com
Expected for the public commercial host. Install the self-hosted runtime and open the customer-owned console domain.
Customer console redirects to login
Expected when unauthenticated on the self-hosted runtime. Sign in with the configured OIDC provider and verify workspace membership.
Connector says not configured
Add a scoped token or service account in Settings/Helm values and restart connector sync.
Pipeline feels useless in local mode
Use --api-url server mode. Local mode is only a developer smoke path.
Report export missing data
Reports only include evidence that the API has ingested and sanitized. Re-run gate or connector sync.
Detailed troubleshooting table
SymptomLogin shows invalid parameter: redirect_uri
Likely causeOIDC app does not include the exact callback URL.
FixAdd https://release-passport.example.com/releasepassport/v1/auth/callback to authorized redirect URIs.
VerificationOpen the customer runtime /login again and confirm provider redirects back to /console.
SymptomGoogle says OAuth client not found
Likely causeWrong client ID deployed or placeholder value still active.
FixUpdate the OIDC client ID secret/config and restart the API deployment.
VerificationProvider login URL should contain the real client ID.
SymptomCustomer console loops back to login
Likely causeSession cookie domain, allowed group, issuer, or callback mismatch.
FixCheck API logs, cookie domain, OIDC group mapping, and user membership.
VerificationAuthenticated user reaches /console and /settings on the customer domain without another redirect.
SymptomGate returns 401 or 403
Likely causeMissing token, wrong token, wrong workspace, or wrong token scope.
FixRotate token, update CI secret, and confirm service/environment scope.
Verificationreleasepassport gate prints a passport ID instead of auth error.
SymptomGate always HOLD
Likely causeRequired evidence is missing, stale, or scoped to another service name/namespace.
FixMatch service name, namespace, release ID, source SHA, artifact digest, and connector scope.
VerificationPassport detail shows complete evidence and no missing requirement.
SymptomGate blocks unexpectedly
Likely causePolicy is enforce or --fail-on threshold is stricter than rollout maturity.
FixStart shadow, review policy result, then move advisory/enforce deliberately.
VerificationCI exit code matches chosen mode and fail threshold.
SymptomConnector health stale
Likely causeWorker cannot authenticate, query is not allowlisted, or provider URL is wrong.
FixFix secret, scope, provider base URL, query allowlist, and restart worker sync.
VerificationIntegrations page shows fresh last sync and latest evidence.
SymptomPrometheus evidence missing
Likely causeLabels do not match the service/environment or query returns no series.
FixTest the allowlisted query in Prometheus and align service labels.
VerificationPassport evidence timeline includes current p95/error-rate facts.
SymptomKubernetes readiness missing
Likely causeNamespace, label selector, or service account RBAC is wrong.
FixGrant read-only scoped RBAC and confirm labels match workload.
VerificationConnector detail shows rollout status and ready replicas.
SymptomGitOps status unavailable
Likely causeApp name, project scope, or token permission mismatch.
FixLimit token to the correct Argo CD/Flux app and configure app name.
VerificationConnector detail shows health, sync, revision, and previous revision.
SymptomCheckout stays pending
Likely causePayment webhook not received or signature invalid.
FixCheck provider secret, webhook URL, provider status, and API logs.
VerificationGET /billing/status shows active after a valid successful payment event.
SymptomProduction feature not unlocked
Likely causeEntitlement not active for the workspace.
FixConfirm checkout workspaceId, webhook success, license status, and runtime restart if required.
VerificationGET /license/status shows production entitlement and feature flags.
SymptomDocs or console overflows on mobile
Likely causeA table/code block or long identifier is not constrained.
FixUse responsive wrappers and avoid unbroken public copy.
VerificationCheck 390x844 viewport has no horizontal overflow.
| Symptom | Likely cause | Fix | Verification |
|---|---|---|---|
| Login shows invalid parameter: redirect_uri | OIDC app does not include the exact callback URL. | Add https://release-passport.example.com/releasepassport/v1/auth/callback to authorized redirect URIs. | Open the customer runtime /login again and confirm provider redirects back to /console. |
| Google says OAuth client not found | Wrong client ID deployed or placeholder value still active. | Update the OIDC client ID secret/config and restart the API deployment. | Provider login URL should contain the real client ID. |
| Customer console loops back to login | Session cookie domain, allowed group, issuer, or callback mismatch. | Check API logs, cookie domain, OIDC group mapping, and user membership. | Authenticated user reaches /console and /settings on the customer domain without another redirect. |
| Gate returns 401 or 403 | Missing token, wrong token, wrong workspace, or wrong token scope. | Rotate token, update CI secret, and confirm service/environment scope. | releasepassport gate prints a passport ID instead of auth error. |
| Gate always HOLD | Required evidence is missing, stale, or scoped to another service name/namespace. | Match service name, namespace, release ID, source SHA, artifact digest, and connector scope. | Passport detail shows complete evidence and no missing requirement. |
| Gate blocks unexpectedly | Policy is enforce or --fail-on threshold is stricter than rollout maturity. | Start shadow, review policy result, then move advisory/enforce deliberately. | CI exit code matches chosen mode and fail threshold. |
| Connector health stale | Worker cannot authenticate, query is not allowlisted, or provider URL is wrong. | Fix secret, scope, provider base URL, query allowlist, and restart worker sync. | Integrations page shows fresh last sync and latest evidence. |
| Prometheus evidence missing | Labels do not match the service/environment or query returns no series. | Test the allowlisted query in Prometheus and align service labels. | Passport evidence timeline includes current p95/error-rate facts. |
| Kubernetes readiness missing | Namespace, label selector, or service account RBAC is wrong. | Grant read-only scoped RBAC and confirm labels match workload. | Connector detail shows rollout status and ready replicas. |
| GitOps status unavailable | App name, project scope, or token permission mismatch. | Limit token to the correct Argo CD/Flux app and configure app name. | Connector detail shows health, sync, revision, and previous revision. |
| Checkout stays pending | Payment webhook not received or signature invalid. | Check provider secret, webhook URL, provider status, and API logs. | GET /billing/status shows active after a valid successful payment event. |
| Production feature not unlocked | Entitlement not active for the workspace. | Confirm checkout workspaceId, webhook success, license status, and runtime restart if required. | GET /license/status shows production entitlement and feature flags. |
| Docs or console overflows on mobile | A table/code block or long identifier is not constrained. | Use responsive wrappers and avoid unbroken public copy. | Check 390x844 viewport has no horizontal overflow. |
What to include in a support request
Workspace ID, service name, environment, release ID, and passport ID.
CLI version and command without token values.
Connector type, scope summary, and last sync timestamp.
Policy name, mode, and decision shown in passport detail.
Sanitized API or worker log excerpt with request IDs.
Never include tokens, kubeconfigs, private keys, OIDC secrets, payment provider keys, registry credentials, or raw private evidence.