Troubleshooting
errors and their fixes.

01Build and run

firebase_options.dart not found / Target of URI doesn't exist

You have not connected the app to your Firebase project yet. Run flutterfire configure in that app's folder (how).

MissingPluginException or strange errors after changing packages

flutter clean
flutter pub get

On iOS also run pod install --repo-update in ios/.

The admin panel needs a newer Dart SDK

It needs Dart 3.11.1 or newer: flutter upgrade (Flutter 3.41+).

iOS: "No profiles for …" or signing errors

In Xcode select your own Team under Signing & Capabilities and make sure the bundle ID is registered in your Apple Developer account.

Google Play rejects the bundle as debug-signed

Signing values are missing. Create android/key.properties (how).

02Firebase and Cloud Functions

Functions deploy fails with a Node version error

Use Node 22: nvm use 22, then deploy again.

Deploy fails because of billing, or asks to enable APIs

Switch the project to Blaze and allow the APIs the CLI asks for.

Deploy asks for OWNER_UID or CLAUDE_API_KEY

Set them with firebase functions:secrets:set (a placeholder is fine for an unused feature) and remove any OWNER_UID= line from functions/.env.

permission-denied from Firestore

Rules not deployed, or you are not signed in as an admin. Run firebase deploy --only firestore:rules in crypto_wallet and check firebase use shows your project.

03Admin panel

"Firebase credentials are missing for this build"

The admin was built before flutterfire configure --platforms=web ran in crypto_wallet_admin. Configure and rebuild.

"This account is not authorized for the admin panel"

The email has no admin_users entry. Create the first admin (how) or ask a super admin to invite you.

"Bootstrap is fire-once and an admin already exists"

An admin exists already. Sign in with it and invite others in User Roles.

Saving works but publishing fails with "Admin only"

Your login has no admin claim. A super admin or the owner re-invites you in User Roles; then sign out and in again.

Locked out by the IP allowlist

Firestore console → admin_config/ip_allowlist → set enabled to false, reload.

Lost the authenticator phone

Use a backup code, or ask another super admin to disable MFA for you in User Roles.

04Settings not reaching the app

• You pressed Publish to mobile app after saving.
• You fully closed and reopened the app (release builds fetch at most once an hour).
• kAdminConfigUrl points at your admin and that URL returns JSON.
• The app and the admin use the same Firebase project.

05Swaps and fees

Swaps show a "Simulated" badge or quotes fail with HTTP 400

ZEROX_API_KEY and/or ONEINCH_API_KEY are missing or misspelled. Without both, EVM swaps show indicative prices only.

Swaps work but no fee arrives

• Fee wallet empty or preset set to Free.
• You tested with a PRO account while the PRO waiver is on.
• The swap was on Solana (Jupiter) or another non-0x/1inch route — no fee is collected there (why).
• You did not publish after Apply Fee Config.

"A valid fee wallet address is required when the fee rate is above 0"

Enter an EVM address: 0x followed by 40 hex characters, not all zeros.

06Features

WalletConnect does not connect

Set REOWN_PROJECT_ID (in .env or Admin → System Config → Remote API Keys) and keep walletconnect_enabled on.

Push notifications do not arrive

iOS: upload the APNs key and keep the Push capability. All: the user must allow notifications. Web: fill firebase-messaging-sw.js and build with WEB_PUSH_VAPID_KEY.

A PRO purchase goes through but PRO does not unlock

The store product ID must equal IAP_PRO_WEEKLY_ID and PRO_WEEKLY_PRODUCT_ID; check the store variables in functions/.env, that ANDROID_PACKAGE_NAME is your app ID, and the logs of validateAppleReceipt / validateGoogleReceipt.

"AI features are not configured for this deployment"

Portfolio Brain needs the CLAUDE_API_KEY secret. Set it and redeploy callPortfolioBrain.