Troubleshooting
Use this table to narrow down operational issues. When in doubt, verify queue health and recent deploys first.
Symptom reference
| Symptom | Likely cause | What to check |
|---|---|---|
| Redirect works but no new scans in analytics | Ingestion queue not running, or quota exceeded | Workers on ingestion queue; workspace monthly scan limit; failed jobs table. |
| Analytics delayed by minutes | Normal under load; geo lookup slow | Queue latency; job retries; location provider timeouts. |
| CSV export returns 403 | Role lacks export permission | User needs owner, admin, or analyst for analytics export policy. |
| API returns 401 | Missing or invalid Bearer token | Token created for same user; not expired; correct Authorization header. |
| API returns 403 on workspace routes | Token missing workspace ability | Recreate token; ensure ability matches workspace slug (workspace:your-slug). |
| Billing portal error | Stripe customer missing or misconfigured keys | Workspace stripe_id; Stripe keys; Cashier webhook delivery. |
| Alerts never email | Mail misconfigured or schedule not running | Mail env vars; cron for schedule:run; spam filters. |
| Old scans still present after retention change | Purge job not run yet | Daily purge schedule; PRIVACY_SCAN_RETENTION_DAYS value. |
| Webhook deliveries keep failing | Destination rejects signature or endpoint unavailable | Verify worker on analytics queue, endpoint URL health, and HMAC verification as sha256=HMAC(timestamp + "." + canonical JSON payload) using X-QR-Webhook-Timestamp and X-QR-Webhook-Signature. |
Escalation
For issues that span billing contracts, data residency, or custom MSA terms, route the conversation through your account contact so engineering and legal can respond together.