Troubleshooting & FAQ

When something doesn't work, the quickest path to resolution is almost always the JSONL audit trail. Every PR emits one event per line — stage start, stage finish, LLM call, rule firing, config read. Read the trail, find the last successful event, and you'll usually see the failure on the next line.

My PR didn't get a check-run

1. Confirm the GitHub App is installed on the org AND the specific repo. At /dashboard/repositories, the repo should show a green install badge.
2. Check PR state — draft PRs are skipped by default until the ready_for_review event.
3. Webhook was delivered? Look for github.webhook.received in the trail. If missing, inspect GitHub Settings → Webhooks → Recent Deliveries for a 401/403 — usually means a webhook secret rotation.
4. Check /admin/queues. If analysis has stuck jobs, the reaper will mark them after 10min; requeue manually if needed.

Check-run failed unexpectedly

"Unexpected" almost always means a merge-policy hit the author didn't expect. Look at the PR comment — Veriva names the stage and rule. If it's a STATIC finding, the rule docs link explains it. If it's a deny-rule hit, the policy page (/dashboard/settings/policy) shows the matching rule.

Pipeline stopped halfway with BUDGET_EXCEEDED

Your per-PR cost ceiling kicked in. Default is $0.50 (Pro) / $2.00 (Ultra). Huge diffs on Opus-routed repos are the usual cause. Options:

• Split the PR into smaller diffs.
• Override the ceiling for this repo in /dashboard/settings/policy.
• Switch the repo to Sonnet-only routing in the admin Model Routing tab.

I'm locked out of MFA

Use a recovery code from the enrollment flow. Lost them? An OWNER can grant a 72-hour grace override from /dashboard/settings/account → Members. If the locked-out user IS the OWNER, contact support — we can verify via the billing email on file.

My Webhook hook isn't receiving POSTs

1. Is the hook enabled? Toggle at /dashboard/settings/hooks.
2. Check the 5s timeout — slow receivers get retried up to 3 times then dropped.
3. Verify HMAC — every POST carries x-veriva-signature.
4. Audit trail — look for hook.dispatch and hook.response lines.

Veriva didn't detect my agent

Detection order: x-veriva-agent-id header → Co-Authored-By: trailer → PR-body marker → HUMAN. If your agent CLI doesn't set any of these, register a custom AgentIdentity row at /dashboard/agents and pass its token in the header from your CI.

Query failed with "permission denied"

Self-hosted deployments only. This is row-level security working as intended — the veriva_app role requiresapp.current_org_id to be set on the session. Middleware sets it automatically; a manual psql session will not.

Pipeline p95 latency is over 90s

1. Check Bedrock region health at /admin/health. If primary (us-east-1) is degraded, failover to secondary is automatic.
2. Per-tenant concurrency limit — Hobby 1, Pro 5, Ultra 20. Noisy neighbors don't affect you.
3. Prompt cache miss? Check hit-rate in /admin/overview. Cold repos always take one Opus/Sonnet call to warm.

Still stuck?

Open the help widget (bottom-right of any dashboard page) and submit a ticket. Include: the PR URL, the pipeline run ID (from the URL on the PR detail page), and anything unexpected from the JSONL trail. Support SLA: Pro 24h, Ultra 8h, Enterprise 4h.