Troubleshooting
Diagnose configuration, authentication, contract, subscription, upload, and push failures by boundary.
| Symptom | Boundary to check | Resolution |
|---|---|---|
| Client shows a configuration error at launch | Backend preset | Set the selected mode's required base URL and origin. Do not configure fallback behavior. |
Auth returns 403 MISSING_OR_NULL_ORIGIN | Trusted origin | Make the client's exact request Origin match the host allow-list. Do not confuse it with a deep-link scheme. |
| Native social sign-in is rejected | OAuth audience | Configure the active mobile solution's Apple bundle ID and Google client IDs on the host. |
get-session returns 200 with null | Session lifecycle | Treat the session as invalid, clear secure state and caches, and return to sign-in. |
App API returns 401 UNAUTHENTICATED | Bearer session | Invalidate once; do not retry in a loop or fall back to Supabase. |
| API schema or error code differs by host | Contract drift | Compare the host mirror to the canonical OpenAPI and run conformance tests. |
| Purchase succeeds but another surface stays locked | Webhook and identity | Verify webhook authorization, explicit product mapping, and RevenueCat user identity. Refresh the host snapshot. |
| Upload presign succeeds but completion fails | Storage boundary | Verify MIME/size limits, direct-upload response, object key, and host storage credentials. |
| Android test push is unavailable | Capability boundary | Expected in v1: register the FCM token, but do not call the APNs-only test endpoint. |
| Expo Unified fails on Web | Runtime restriction | Expected: Unified supports Expo iOS/Android only. Build Web in Standalone mode. |
Include the host request ID and stable error code in support reports. Never include Bearer tokens, cookies, presigned URLs, secrets, or full provider payloads.