FAQ & Troubleshooting

Flutter pub get fails with version conflicts

Solution:

# Clean and retry
flutter clean
flutter pub cache repair
flutter pub get

CocoaPods installation fails (iOS)

Solution:

# Update CocoaPods
sudo gem install cocoapods

# Clean and reinstall
cd ios
pod deintegrate
pod install --repo-update
cd ..

Gradle build fails (Android)

Solution:

# Clean Gradle cache
cd android
./gradlew clean
./gradlew --stop

# Delete cache and retry
rm -rf ~/.gradle/caches/
cd ..
flutter run

Node modules installation fails

Solution:

# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
cd functions
rm -rf node_modules
rm package-lock.json
npm install
cd ..

Firebase initialization failed

Cause: Missing or incorrect Firebase configuration files.

Solution:

# Reconfigure Firebase
flutterfire configure --project=YOUR_PROJECT_ID --yes

# Verify files exist:
# - lib/firebase_options.dart
# - android/app/google-services.json
# - ios/Runner/GoogleService-Info.plist

Cloud Functions deploy fails

Possible causes:

• Not on Blaze plan
• Node.js version mismatch
• TypeScript compilation errors

Solution:

# Check Node.js version (should be 18+)
node --version

# Build functions locally to check for errors
cd functions
npm run build
npm run lint

# Deploy with verbose logging
firebase deploy --only functions --debug

Authentication not working

Checklist:

• Verify auth providers are enabled in Firebase Console
• Check SHA-1 fingerprint is added for Android (Google Sign-In)
• Verify URL schemes are configured for iOS
• Check if using emulators (USE_FIREBASE_EMULATORS=true)

Firestore permission denied

Solution:

# Deploy security rules
firebase deploy --only firestore:rules

# Check rules in Firebase Console → Firestore → Rules
# Use Rules Playground to test

Push notifications not received

Checklist:

• iOS: APNs key uploaded to Firebase Console
• iOS: Push Notification capability added in Xcode
• Android: Check if running on emulator (use real device)
• Web: VAPID key configured correctly
• Verify FCM token is being saved to Firestore

Google Maps not showing

Checklist:

• API keys are correct in environment files
• Maps SDK is enabled in Google Cloud Console
• API keys have correct restrictions
• Billing is enabled for the Google Cloud project

App crashes on startup

Debug steps:

# Run with verbose logging
flutter run --verbose

# Check for Firebase initialization
# Verify all env variables are set
# Check for null safety issues in logs

iOS build fails with signing error

Solution:

1. Open ios/Runner.xcworkspace in Xcode
2. Select Runner target → Signing & Capabilities
3. Select your Team
4. Let Xcode manage signing automatically

Android build fails: "SDK version issue"

Solution: Update compile and target SDK in android/app/build.gradle.kts:

android {
    compileSdk = 34

    defaultConfig {
        minSdk = 23
        targetSdk = 34
    }
}

Web build shows blank page

Checklist:

• Check browser console for errors (F12)
• Verify Firebase config for web platform
• Check if hosting rewrites are configured correctly
• Try building with --web-renderer html

Cannot login to admin panel

Checklist:

• User exists in Firebase Authentication
• Admin document exists in admins collection
• Admin status is "active"
• Cloud Functions are deployed

Debug: Check function logs:

firebase functions:log --only validateAdminAccess

Admin invite email not sent

Checklist:

• Trigger Email extension is installed
• SendGrid API key is valid
• Sender email is verified in SendGrid
• Check mail collection for pending emails

Debug: Check extension logs in Firebase Console → Extensions

Dashboard metrics not loading

Solution:

• Ensure getDashboardMetrics function is deployed
• Check user has admin permissions
• Verify Firestore indexes are created

App is slow on first load

Causes:

• Cold start for Cloud Functions
• Large initial data load

Solutions:

• Use pagination for lists
• Enable function min instances for critical functions
• Implement proper loading states

Map performance issues

Solutions:

• Limit number of markers displayed
• Use clustering for many markers
• Load markers on demand based on viewport