Skip to main content

Troubleshooting

Quick links: Frontend • Backend

Backend​

Common issues:

  • Missing FIREBASE_SERVICE_ACCOUNT_BASE64

    • Symptoms: Admin SDK init fails in API routes. Use /api/debug-env.

  • Stripe webhook signature verification fails

    • Ensure raw body is read and STRIPE_WEBHOOK_SECRET matches dashboard.

  • OAuth callback URL mismatch

    • Verify provider dashboards use exact callback URL from Functions config.

  • Billing portal returns "No Stripe customer for user"

    • Ensure users/{uid}.stripeCustomerId is set during verify-session.

  • Storage upload CORS/preflight fails (status 403/404/0 on firebasestorage.googleapis.com)

    • Ensure the correct bucket name is used in env NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET.
    • Apply CORS to the bucket with gsutil cors set path/to/cors.json gs://<bucket> using the user-created config described in Setup → Firebase; the checked-in cors.json is only an example template.
    • Confirm Firebase Auth → Authorized domains includes your web origins.

API Error Debugging​

  • Error Logs: Check errorLogs collection in Firestore for detailed error tracking
  • Request Tracking: Use X-Request-ID header to correlate requests across logs
  • Development Mode: Set NODE_ENV=development for detailed error responses with stack traces
  • Error Codes: Reference the API Error Handling documentation for error code meanings

Diagnostics:

  • Check Next.js server logs and Firebase Functions logs.
  • Log event.type for unhandled Stripe events to refine webhook handling.

Related frontend: see Frontend

Frontend​

  • After sign-in, ensure the client posts the ID token to /api/auth/session to create __session.
  • Stripe success page must call /api/verify-session with sessionId from the URL.
  • Integration connect buttons should call startAuth(platform, idToken, window.location.href, isLocal) and then redirect to the returned { authUrl }.

Related backend: see Backend