● Ship · When something is wrong
Troubleshooting
symptom, cause, fix.
The problems you are most likely to meet, in the order you meet them. Press / and search for the exact message.
01The app does not start properly
| Symptom | Cause | Fix |
|---|---|---|
| The app shows a setup screen instead of sign-in | app/lib/firebase_options.dart is still the placeholder with empty values. | Run flutterfire configure in app/ (how), or use DEMO_MODE=true / USE_EMULATOR=true. |
Every action fails with permission-denied or unauthenticated in a debug build | App Check: the debug token of this device is not registered. | Copy the debug token from the device log into Firebase console → App Check → Manage debug tokens. Or set ENFORCE_APP_CHECK=false in firebase/functions/.env while you set up, and redeploy. |
Actions fail with not-found or internal | The app calls Functions in a different region than you deployed to. | Build with --dart-define=FUNCTIONS_REGION=<your region>, matching firebase/functions/.env. |
| Google sign-in fails on Android | The SHA-1/SHA-256 fingerprints of your signing key are missing in Firebase. | Add them in Project settings, run flutterfire configure again. |
| Sign in with Apple fails | The capability or the Firebase Apple provider is not set up. | Add the capability in Xcode; enable Apple in Firebase Authentication. |
pod install fails with a deployment target error | The plugins need iOS 15. | Keep platform :ios, '15.0' in the Podfile and set Minimum Deployments 15.0 in Xcode. |
02Ads and points
| Symptom | Cause | Fix |
|---|---|---|
| Users watch videos but get no points | The network's callback does not reach your function, or its signature fails. | Check the callback URL in the network's dashboard (URLs), the secret in the console, and Firebase console → Functions → logs. A wrong secret gives 403. |
| Points arrive only after a delay | Networks send callbacks from their servers, usually within seconds, sometimes later. | Normal. The balance updates by itself when the callback is applied (the app listens to the user document live). |
| Only Google test ads appear | AdMob is selected and no unit ids are entered, so the app uses Google's test units. | Enter your unit ids in console → AdMob units. |
| No ads at all with AppLovin, Unity or ironSource | That network's required ids are empty; the app shows nothing until they are set. | Fill them in; the console Status page lists what is missing. New ad units can take time before the network serves fill. |
| "Daily ad limit reached. Come back tomorrow." | adDailyCap reached for this UTC day. | Expected. Change it in Rewards economy if you want. |
| "Please wait N s before the next ad." | adCooldownSeconds. | Expected. |
| Many fraud flags | Callbacks that do not match a pending session of the same user, or arrive after the session expired. | Review them in console → Fraud flags. A wrong ironSource user id parameter shows up here: test one real callback (note). |
| Unity callbacks are refused | The secret is missing; Unity only sends it after you e-mail their support. | Enter the secret Unity support sends you as Unity S2S secret. |
03Operator console
| Symptom | Cause | Fix |
|---|---|---|
| I lost the setup code | It is printed in the log on each start until an owner exists. | Restart the console and read the log again. |
| Status: "Firestore is reachable" fails | No credentials, wrong project or missing role. | Check GOOGLE_APPLICATION_CREDENTIALS (path to the key file) and FIREBASE_PROJECT_ID; on Cloud Run check the service account roles. |
| Status: "App config written to Firestore" fails | The sync could not write config/public. | Fix Firestore access first; the console writes on the next save or start. |
| Ledger page or Overview counts show an index error | Firestore indexes are missing or still building. | firebase deploy --only firestore:indexes and wait until they are Enabled. |
| Stored secrets can no longer be read | ADMIN_SECRET_KEY changed or was lost. | Restore the old key. Without it, enter the secrets again. |
| Settings changes do not reach the app | The app listens to config/public live, so a change normally arrives within seconds. If not, the console could not write it. | Check the console Status page ("App config written to Firestore") and the device's network. A network switch also needs the ad SDK to initialise again: reopen the app. |
| Everything answers 403 and a "Demo console" banner shows | ADMIN_DEMO_PASSWORD is set. | Remove it (and ADMIN_DATA) on your real console. |
04Development
| Symptom | Cause | Fix |
|---|---|---|
| Emulators do not start | Java is missing or older than 21. | Install Java 21+; check java -version. |
| The app on the Android emulator cannot reach the Firebase emulators | Wrong host. | Leave EMULATOR_HOST empty (the app uses 10.0.2.2); on a real phone set it to your computer's IP. |
| The emulator says purchases or callbacks are refused | Real store and network calls do not work in the emulator. | Use devCompleteAdSession (automatic in emulator builds) and test purchases on store test builds. |