AgentFlow Enterprise Docs
Error Codes & Troubleshooting
Practical meaning, cause, user impact, operator fix targets, and safe log guidance for common operational errors.
Troubleshooting Reference
| Code | Meaning | Common cause | User-facing impact | Files/routes to inspect | Safe log guidance |
|---|---|---|---|---|---|
AUTH_SESSION_MISSING | No valid Supabase session is available. | Expired cookies, missing login, or browser blocking auth cookies. | Protected routes redirect to /login; APIs return 401. | proxy.ts, lib/supabase-server.ts, /api/ai/qualify-lead. | Log user id only after auth succeeds; do not log cookies or tokens. |
AUTH_MEMBERSHIP_REQUIRED | A user exists but no active organization membership can be resolved. | Organization bootstrap failed or membership row is missing/inactive. | Dashboard or workspace actions cannot load tenant data. | lib/server/organization.ts, lib/organizations/ensureUserOrganization.ts, organization_members. | Log organization id and membership id if present; avoid dumping user metadata. |
RLS_ACCESS_DENIED | Supabase rejected a tenant-scoped query under RLS. | Wrong organization id, inactive membership, or browser attempting a server-only write. | Rows appear missing or writes fail. | supabase/migrations/20260518070000_harden_rls_tenant_isolation.sql, docs/security/supabase-rls-tenant-isolation.md. | Log table name and policy stage, never service-role keys or row payloads. |
CHECKOUT_SESSION_FAILED | Stripe Checkout session creation failed. | Missing Stripe key/price id, unauthenticated user, organization bootstrap failure, or Stripe API error. | User cannot continue to payment. | app/api/checkout/stripe/route.ts, lib/stripe/plans.ts, components/CheckoutButton.tsx. | Log selected plan and missing env names only; do not log Stripe secrets. |
STRIPE_WEBHOOK_SIGNATURE_FAILED | Stripe signature verification failed. | Wrong webhook secret, endpoint mismatch, replayed payload, or non-raw body. | Webhook returns 400 and no billing update is processed. | app/api/webhooks/stripe/route.ts, Stripe Dashboard webhook settings. | Log event delivery id if available, not raw payload or signing secret. |
STRIPE_WEBHOOK_DUPLICATE_EVENT | A Stripe event id already exists in billing_events and has processed_at set. | Stripe retry or manual replay of a processed event. | No duplicate subscription mutation should occur. | billing_events, insertOrLoadBillingEvent in app/api/webhooks/stripe/route.ts. | Log stripe_event_id and duplicate status only. |
SUBSCRIPTION_INACTIVE | No active or trialing subscription is available for the organization. | Canceled, unpaid, past_due, incomplete, incomplete_expired, paused, missing webhook, or expired period. | AI qualification and lead usage-gated actions can return 402. | lib/usage.ts, lib/billing/access.ts, subscriptions. | Log normalized status and organization id, not customer billing details. |
OPENAI_REQUEST_FAILED | OpenAI returned an error or invalid output. | Missing key, model issue, provider outage, invalid JSON, or prompt response validation failure. | Qualification returns 503. | app/api/ai/qualify-lead/route.ts, OPENAI_API_KEY, OPENAI_MODEL. | Log provider error class and request stage; do not log full lead message by default. |
OPENAI_TIMEOUT | The qualification call exceeded the route's timeout window. | Provider latency or network timeout. | Qualification returns unavailable and no result is saved. | qualifyLead in app/api/ai/qualify-lead/route.ts. | Log timeout stage and model only. |
RATE_LIMITED | The request exceeded configured limits or abuse checks. | Too many requests per minute, honeypot filled, spam-like payload, or repeated links. | API returns 429. | lib/rate-limit.ts, /api/ai/qualify-lead, /api/leads. | Log rate-limit key prefix and reset time, not IP plus payload together. |
SUPABASE_QUERY_FAILED | A Supabase read/write failed. | Missing table, schema cache lag, RLS denial, invalid row shape, or service-role configuration issue. | Data fails to load or persist. | lib/supabase-admin.ts, relevant route handler, Supabase logs. | Log Supabase error code and message; redact row values that contain PII. |
ENV_MISSING | A required environment variable is absent. | Vercel env not configured for the current environment or local .env.local missing a key. | Checkout, auth, AI, email, or webhook routes return configuration errors. | .env.example, lib/env.ts, route-specific env checks. | Log variable names only; never log values. |
INTEGRATION_NOT_CONFIGURED | An optional integration does not have the required env variables. | HubSpot, Slack, Google, or outbound webhook variables are absent. | Core lead qualification can still succeed; integration event is skipped or marked not_configured. | lib/integrations/env.ts, lib/integrations/dispatch.ts. | Log provider name and readiness state only. |
HUBSPOT_SYNC_FAILED | HubSpot contact create/update failed. | Invalid token, field mapping issue, API outage, or HubSpot validation error. | Lead is saved but hubspot_sync_status may become failed. | lib/integrations/hubspot.ts, /api/integrations/hubspot/sync-lead, /api/webhooks/hubspot. | Log HubSpot status code and safe error, not access token or full contact payload. |
SLACK_WEBHOOK_FAILED | Slack notification dispatch failed. | Webhook URL invalid, Slack API rejected bot token/channel, or network error. | Lead qualification still succeeds; Slack event records failed. | lib/integrations/dispatch.ts, Slack env variables. | Log provider status and HTTP code only. |
STATUS_PAGE_NOT_CONFIGURED | NEXT_PUBLIC_STATUS_PAGE_URL is missing. | External status page has not been linked. | /status remains available but cannot link to the external page. | app/status/page.tsx, .env.example. | No secret risk; log missing variable name only. |
These docs describe implementation readiness and configuration. They are not a SOC 2, ISO 27001, penetration test, or contractual SLA claim.