Troubleshooting.
What the message means and how to check.

01Three first checks

1. Console → Status → Re-run checksNames missing keys, invalid keys, skipped catalog lines, caps that are hit, missing ad ids and store verification.
2. Health of the API

   curl <API_BASE_URL>/v1/health
   # {"ok":true,"version":"2.0.0","ai":"ok"|"no_key"|"capacity","images":…,
   #  "tts":"off"|"no_key"|"capacity"|"ok","transcribe":…,"video":…,
   #  "discover":"off"|"no_key"|"stale"|"failing"|"ok","demo":false,"time":"…"}

   Terminal: macOS or Linux as shown; on Windows use WSL or Git Bash (how).

   You can also open that address in a browser.
3. Functions logsFirebase console → Functions → Logs, or firebase functions:log --only api from firebase/. Lines are chat, chat failed, images, image generation failed, store verification error, AdMob SSV keys unavailable, moderation endpoint failed…, unhandled API error. They carry ids, model, status and HTTP status, never message text.

02The app shows a setup screen

03"No AI model is switched on yet"

Cause: no chat model is enabled, or its provider has no key. /v1/health shows "ai":"no_key".

Check: Console → Chat models: a model with status "Needs a key" is written to the app as disabled. Set the key (AI providers & keys), enable at least one free model, Save, then restart the app. curl <API_BASE_URL>/v1/config must list it under models (the API caches the config 60 s).

04Provider key errors

In the app: "The AI service is temporarily unavailable. Please try again." The chat stream ends with event: error and "error":"upstream_unavailable"; the message is refunded. In the logs: chat failed with httpStatus.

05Other chat and image messages

06Answers arrive all at once, or are cut off

Cause: something between the app and the function buffers the Server-Sent Events stream (a CDN, a corporate proxy, a reverse proxy in front of a custom domain) or closes long requests.

Check the raw stream with curl -N (use the dev API locally, or your API with a real Firebase ID token):

curl -sN -X POST http://localhost:8787/v1/chat \
  -H "Authorization: Bearer demo-test123456" -H "content-type: application/json" \
  -d '{"model":"claude-haiku","messages":[{"role":"user","content":"Hello"}],"unlock":"allowance"}'
# event: meta   data: {"messageId":"…","model":"claude-haiku","label":"Muse Fast","charged":"allowance",…}
# event: delta  data: {"text":"This "}
# event: delta  data: {"text":"is "}   … then event: done

Terminal: macOS or Linux as shown; on Windows use WSL or Git Bash (how).

If the delta lines appear one by one directly on the function URL but all at once through your domain, the proxy buffers. The backend already sends X-Accel-Buffering: no for streams; configure your proxy not to buffer text/event-stream (nginx: proxy_buffering off;) and to allow requests up to 300 seconds. The direct cloudfunctions.net URL streams.

07CORS errors (web build)

The API answers CORS itself with Access-Control-Allow-Origin: * and allows the Authorization and Content-Type headers. Check the preflight:

curl -si -X OPTIONS <API_BASE_URL>/v1/chat -H "Origin: https://example.com" \
  -H "Access-Control-Request-Method: POST" -H "Access-Control-Request-Headers: authorization,content-type"
# HTTP/1.1 204 · access-control-allow-origin: * · access-control-allow-headers: Authorization,Content-Type

Terminal: macOS or Linux as shown; on Windows use WSL or Git Bash (how).

If this header is missing, the request did not reach the API: the URL is wrong (a 404 page from Google has no CORS headers), the path lacks the function name (…/api/v1/…), or a proxy strips headers.

08Firebase credentials of the console

09Images generate but the app gets 500 internal

Cause: the function's service account cannot sign Storage URLs. Logs show unhandled API error, typically mentioning signBlob or iam.serviceAccounts.signBlob.

Fix: enable the IAM Service Account Credentials API and grant <project-number>-compute@developer.gserviceaccount.com the role Service Account Token Creator on itself (Installation, step 2). No redeploy needed.

10Purchases: 503 iap_unconfigured and other answers

11Ads do not show, or test ads appear in a release build

See Ads → common problems: a step-by-step checklist for ads that do not show, test ids in release builds and SSV callbacks that never arrive.

12Rewarded ads with server-side verification

• The app keeps waiting after the ad: POST /v1/rewarded answers 404 not_found "The reward is not confirmed yet." until AdMob's callback arrives. Check that the rewarded unit's SSV callback URL is exactly <API_BASE_URL>/v1/rewarded/ssv and reachable from the internet; AdMob's "Verify URL" button sends a test.
• Callback answers 404 "Server-side verification is not enabled.": switch on Ads → Rewarded ads: server-side verification and save.
• Rewards never arrive while SSV is on and Unity Ads or LevelPlay served the rewarded ad: SSV works with AdMob only. Turn SSV off, or serve rewarded ads only with AdMob (Ads → rewarded).
• Callback answers 400 "Invalid signature." or log AdMob SSV keys unavailable: the backend could not load or match Google's verifier keys; retry, and check outbound network of the function.
• 402 limit_reached "Today's rewarded unlocks are used up.": the daily rewarded limit (Limits).

13Push campaigns do not arrive

• Console → Push campaigns: status stays scheduled → sendCampaigns is not running. Firebase console → Functions should list it; Cloud Scheduler must be enabled (it runs every 5 minutes).
• Status failed with an error → the log line sendCampaigns shows the count; check that Cloud Messaging is enabled in the project.
• Nothing on iOS → the APNs key is not uploaded in Firebase, the Push Notifications capability is missing, or the user declined notifications (Settings → Notifications).
• Nothing anywhere → the device never registered: the app needs Firebase configured (not the demo) and notification permission. The segment "users on a plan" only reaches devices that had a plan when they last subscribed to topics.

14Sign-in buttons fail

• A button shows but fails → the same provider is not enabled in Firebase Authentication. Enable it there, or switch the button off in Console → Sign-in methods.
• Google on Android fails → add the SHA-1 and SHA-256 of your upload and app-signing keys in Firebase (Release) and run flutterfire configure again.
• Google on iOS fails or the app closes when the Google page should return → Info.plist still has the placeholder URL scheme: paste your REVERSED_CLIENT_ID from GoogleService-Info.plist (Release → iOS sign-in).
• Apple fails → add the Sign in with Apple capability in Xcode and configure the Apple provider (service id) in Firebase.

15Voice and captions

16Video Studio

17Discover is empty or missing

18Web build: blank page or console errors about Content-Security-Policy

If you serve the web build with a strict Content-Security-Policy like the demo's (no 'unsafe-inline', no 'unsafe-eval'), build it with --csp --no-web-resources-cdn and allow 'wasm-unsafe-eval' in script-src. A browser console message "Refused to apply inline style" after a Flutter upgrade means the two sha256 style hashes changed: copy the new hashes from the message into your host's Content-Security-Policy header (the full policy is on Deployment → web build). "Refused to connect" to fonts.gstatic.com means the policy lacks it in connect-src and font-src. See Deployment → web build.

19Build problems

• flutter pub get fails on the SDK constraint → Flutter older than 3.41 / Dart 3.11. flutter upgrade.
• iOS pod install errors → cd ios && pod repo update && pod install, and open Runner.xcworkspace, not the project file.
• Android "Gradle requires Java 17" style errors → use the JDK bundled with Android Studio (flutter config --jdk-dir <path>).
• Google Play rejects the bundle as debug-signed → android/key.properties missing (Android signing).
• tool/check_ad_ids.sh --release prints FAILED → the AdMob app ids are still Google's test ids.