Troubleshooting

​

Permission Issues

​

Permission not granted on Android

Symptoms: requestNotificationPermission() returns false on Android 13+

Solutions:

• Ensure POST_NOTIFICATIONS permission is in AndroidManifest.xml
• For Android 13+, permission must be requested at runtime
• Test on a physical device (permissions may behave differently on emulators)

AndroidManifest.xml should include:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>

​

iOS permission issues

Symptoms: Permission requests not showing or notifications not working

Solutions:

• Verify “Push Notifications” capability is enabled in Xcode project settings
• Check “Background Modes” capability has “Remote notifications” enabled
• Ensure Info.plist includes UIBackgroundModes configuration
• Test on a physical device (push notifications don’t work on simulator)

​

Firebase Configuration Issues

​

Firebase setup problems

Symptoms: Build errors, FCM token not generated, notifications not received

Solutions:

• Verify google-services.json is in the correct location: android/app/google-services.json
• Check that Firebase project is properly configured with your app’s package name
• Ensure Google Services plugin is applied in the correct build.gradle files
• Verify classpath is added to project-level build.gradle

Project-level android/build.gradle:

buildscript {
  dependencies {
    classpath 'com.google.gms:google-services:4.3.15'
  }
}

App-level android/app/build.gradle:

// At the very bottom
apply plugin: 'com.google.gms.google-services'

​

Link Handling Issues

​

Internal routes not working

Symptoms: App opens but doesn’t navigate to internal pages like /profile, /settings

Solutions:

• Verify navigatorKey is assigned to MaterialApp (see Quick Start guide)
• Check that routes are properly defined in your app
• Ensure autoHandleLinks: true is set in initialize() if you want automatic link handling

​

External links not opening

Symptoms: Links like mailto:, tel:, sms:, or custom schemes don’t open from notifications

Solutions:

• Android: Add the specific schemes to your <queries> block in AndroidManifest.xml
• iOS: Add schemes to LSApplicationQueriesSchemes in Info.plist if using canLaunchUrl() checks

Android configuration:

<queries>
  <!-- Basic web URLs (already in Platform Setup) -->
  <intent>
    <action android:name="android.intent.action.VIEW" />
    <data android:scheme="http" />
  </intent>
  <intent>
    <action android:name="android.intent.action.VIEW" />
    <data android:scheme="https" />
  </intent>
  
  <!-- Email links -->
  <intent>
    <action android:name="android.intent.action.VIEW" />
    <data android:scheme="mailto" />
  </intent>
  
  <!-- Phone calls -->
  <intent>
    <action android:name="android.intent.action.VIEW" />
    <data android:scheme="tel" />
  </intent>
  
  <!-- SMS -->
  <intent>
    <action android:name="android.intent.action.VIEW" />
    <data android:scheme="sms" />
  </intent>
  
  <!-- Custom deep link schemes -->
  <intent>
    <action android:name="android.intent.action.VIEW" />
    <data android:scheme="yourapp" />
  </intent>
</queries>

iOS configuration:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>mailto</string>
  <string>tel</string>
  <string>sms</string>
  <string>yourapp</string>
</array>

​

Build Issues

​

iOS build issues

Symptoms: Compilation errors, pod install failures

Solutions:

• Clean and rebuild: flutter clean && flutter pub get
• Update Podfile with the correct configuration
• Run cd ios && pod install --repo-update
• Ensure iOS deployment target is 12.0 or higher

​

Android build issues

Symptoms: Gradle build failures, dependency conflicts

Solutions:

• Ensure minimum SDK version is API 21 or higher
• Verify all required permissions and services are in AndroidManifest.xml
• Check that google-services.json is valid and matches your package name
• Clean build: flutter clean && flutter build android

​

Runtime Issues

​

Notifications not received

Symptoms: Device identified successfully but notifications don’t arrive

Solutions:

• Verify device is identified with correct project ID format (prj_XXXXXXXXX)
• Check notification permission is granted
• Ensure app is properly registered with Firebase (Android)
• Test with a simple notification first
• Verify the PNTA project is active and configured correctly

​

Memory leaks from streams

Symptoms: App performance degrades over time

Solutions:

• Always cancel stream subscriptions in dispose() method
• Use StreamSubscription variables to track and cancel subscriptions
• Don’t create multiple listeners for the same stream

Correct pattern:

class _MyWidgetState extends State<MyWidget> {
  late StreamSubscription _subscription;

  @override
  void initState() {
    super.initState();
    _subscription = PntaFlutter.foregroundNotifications.listen((payload) {
      // Handle notification
    });
  }

  @override
  void dispose() {
    _subscription.cancel();
    super.dispose();
  }
}

​

Plugin initialization issues

Symptoms: Methods throw errors or don’t work as expected

Solutions:

• Ensure initialize() is called before any other plugin methods
• Call WidgetsFlutterBinding.ensureInitialized() before initialize()
• Verify initialize() is awaited properly

​

Platform-Specific Issues

​

Android 13+ specific problems

Symptoms: Different behavior on newer Android versions

Solutions:

• Test notification permissions on Android 13+ devices
• Ensure POST_NOTIFICATIONS permission is properly requested
• Some features may require targeting SDK 33+

​

iOS specific problems

Symptoms: Different behavior on iOS vs Android

Solutions:

• Test on physical iOS devices (simulator limitations)
• Verify provisioning profile includes push notification entitlement
• Check iOS deployment target meets minimum requirements

​

Getting Help

If you’re still experiencing issues:

1. Check the example app for a complete working implementation
2. Review your implementation against the Quick Start Guide
3. Verify platform setup following the Platform Setup Guide
4. File an issue on the GitHub repository with:
   • Flutter version (flutter --version)
   • Plugin version
   • Platform (iOS/Android)
   • Detailed error messages
   • Minimal reproduction code