| Symptom | Cause and fix |
|---|
| Setup screen "Set your API address" | The build has no API_BASE_URL. Run or build with --dart-define=API_BASE_URL=https://<region>-<project>.cloudfunctions.net/api, no trailing slash. |
| Setup screen "Connect your Firebase project" | lib/firebase_options.dart is still the placeholder. Run flutterfire configure in app/ (Installation). |
| "Market data is temporarily unavailable" | The API answered 503 upstream_unavailable: every provider failed and nothing was cached. Usually CoinGecko's keyless rate limit. Enter a free CoinGecko Demo key, and a CoinMarketCap key for failover (Data providers). |
| A "Cached" label on data | The provider failed and the last cached value is shown ("stale": true). It clears on the next successful fetch. |
| The "All" chart shows only one year | CoinGecko's Public and Demo plans serve 365 days of history ("limitedTo":"1y"). A Pro plan serves the full history. |
| Charts or exchange tickers missing while prices work | They come only from CoinGecko. CoinMarketCap can replace prices, not history. |
| "The account could not be deleted. Please try again." | DELETE /v1/me failed: no network, more than 5 tries in a minute, or a server error (Functions → Logs). Nothing is lost by retrying; a repeated deletion is safe (Account deletion). |
| A Google, Apple or e-mail sign-in button shows "Sign-in failed" | That provider is not enabled under Firebase → Authentication → Sign-in method, or (Apple) the capability or provider settings are missing (Sign-in methods). Enable the provider, or switch the button off in the console under Settings → Sign-in methods. |
| "This account has been suspended" | The user is banned in the console (Users page). Unban there. |
| Wallet: "This address is not valid for the selected chain" | Wrong chain or format (formats). Bitcoin xpubs are not supported. |
| Wallet shows fewer tokens than an explorer | Only tokens among CoinGecko's top 250 are shown; others are counted as hidden (Verified tokens). |
| Wallet lookups fail at busy times | The free public RPC endpoint is rate-limited. Add your own RPC URL in Console → Wallet chains. |
| No ads | Ads are off by default: switch on Show ads and at least one placement, and enter the ids. Pro and Remove-ads users never see ads. Release builds never use test ids. New ad units can take time to fill. |
| Purchase fails with "The store is not available on this device" | If the API log shows 503 iap_unconfigured, store verification is not set up in the console (Purchases). |
| Purchase not granted after paying | The API answered 400 "The purchase could not be verified" (Functions log). Bundle id or package name in the console does not match the build; the product id differs; or the App Store environment is Production while you test in the sandbox. |
