Guides

Fixing common failures

PreFlight probes are deterministic — they tell you exactly what broke and include safe error codes, fix suggestions, and runbook links. This guide covers the failure patterns teams hit most often before launch.

Start in Checks → Fix list. Each failed row maps to a probe key and safe error code. Clear failures before warnings; failed probes block strict Deploy Gates and should open a runbook.

How to use this guide

1. Find the probe. Open Fix list and note the probe_key and safe_error_code.

2. Match the section below. Error codes are stable across runs and exports.

3. Apply the fix. Follow verification steps, then rerun the affected provider or full check.

4. Confirm recovery. Status must change to success before deploying or closing the incident.

---

Stripe failures

Webhook probe failed (STRIPE_WEBHOOK_PROBE_FAILED)

Cause: PreFlight could not prove the configured webhook endpoint accepts signed Stripe events.

Fix:

1. Open Stripe Dashboard → Developers → Webhooks.
2. Confirm the endpoint URL matches the webhook URL saved in PreFlight.
3. Reveal the Signing secret (whsec_…) and update STRIPE_WEBHOOK_SECRET in your app and PreFlight integration.
4. Ensure checkout.session.completed is in the event list.
5. Send a Stripe test event and rerun the Stripe probe.

Related probe keys: stripe_webhook_delivery, stripe_webhook_registry, stripe_config_drift.

Webhook secret missing (STRIPE_WEBHOOK_SECRET_MISSING)

Cause: The Stripe integration has no webhook signing secret configured.

Fix: Copy the signing secret from the Stripe webhook endpoint into the PreFlight Stripe integration form.

Webhook URL missing or blocked (STRIPE_WEBHOOK_URL_MISSING, STRIPE_WEBHOOK_URL_BLOCKED)

Cause: No webhook URL is saved, or the URL fails PreFlight's reachability and security checks.

Fix: Save a publicly reachable HTTPS webhook route. Ensure it returns 2xx to signed POST requests — not 401/403 for unauthenticated probes.

API key rejected (STRIPE_KEY_REJECTED)

Cause: The secret key is invalid, revoked, or belongs to the wrong Stripe mode (test vs live).

Fix: Create a fresh restricted key in Stripe Dashboard. Match test/live mode to your saved project environment.

Registry mismatch (STRIPE_WEBHOOK_ENDPOINT_NOT_FOUND, STRIPE_WEBHOOK_REGISTRY_MISMATCH)

Cause: Stripe's registered webhook endpoints do not include the URL PreFlight expects.

Fix: Register the production webhook URL in Stripe or update PreFlight to match the endpoint you actually deploy.

---

Supabase failures

RLS audit failed (SUPABASE_RLS_AUDIT_FAILED, SUPABASE_RLS_CRITICAL, SUPABASE_RLS_WARNING)

Cause: Missing or overly permissive Row Level Security on monitored schemas.

Fix:

1. Open Supabase Dashboard → Authentication → Policies.
2. Enable RLS on user-owned tables flagged in the probe details.
3. Replace broad anon/authenticated policies with owner or workspace filters (e.g. USING (auth.uid() = user_id)).
4. Rerun the Supabase RLS probe.

Schema sync failed (SUPABASE_SCHEMA_SYNC_FAILED, SUPABASE_SCHEMA_SYNC_STALE)

Cause: Deployed database shape diverges from the expected migration artifact.

Fix:

1. Review the schema-sync report under project Guardrails.
2. Apply missing migrations with supabase db push or your CI migration step.
3. Publish a fresh schema-sync artifact.
4. Rerun the schema-sync probe. Deploy Gates with block_on_schema_drift: true unblock once clean.

Admin API rejected (SUPABASE_ADMIN_CREATE_USER_FAILED)

Cause: The service role key lacks permission or is invalid.

Fix: Copy the service role key from Supabase → Settings → API. Store it only in PreFlight's encrypted integration — never in client bundles.

---

Clerk failures

Secret key rejected (CLERK_SECRET_REJECTED)

Cause: The CLERK_SECRET_KEY is invalid or belongs to a different Clerk instance (Development vs Production).

Fix: Copy the correct secret from Clerk Dashboard → API Keys. Ensure instance type matches your deployed environment.

JWKS unreachable or JWT verification failed (CLERK_JWKS_UNREACHABLE, CLERK_JWT_SIGNATURE_FAILED, CLERK_JWT_CLAIM_MISSING)

Cause: PreFlight cannot fetch JWKS or verify a sample JWT from your Clerk instance.

Fix: Confirm the publishable key and JWT template match production. Verify Clerk's JWKS endpoint is reachable from PreFlight's probe network.

---

Environment and app URL failures

Secret leak detected (environment_secret_leak probe)

Cause: A public HTML or JavaScript payload matched a known secret pattern (sk_live_, service role keys, etc.).

Fix:

1. Identify the leaked pattern in the probe details.
2. Search your codebase and remove the secret from client-side code.
3. Rotate the exposed key immediately in the provider dashboard.
4. Redeploy and rerun App URL checks.

Legal pages missing

Cause: PreFlight could not find /privacy or /terms on the saved project URL.

Fix: Publish privacy and terms pages on your public site. They are required for Stripe approval and enterprise trust reviews.

Webhook reachability (environment_webhook_reachability)

Cause: The saved webhook URL is unreachable, returns non-2xx, or times out.

Fix: Confirm the route is deployed, DNS resolves, and TLS is valid. Check firewall rules that might block PreFlight's probe origin.

---

Cross-provider consistency failures

PreFlight runs consistency probes when live/test keys are mixed across Stripe and Supabase: