> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnta.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions for PNTA Flutter plugin

## Device Registration Issues

### Device registration fails

**Symptoms:** `PntaFlutter.deviceToken` returns `null` after initialization

**Common causes:**

* **Permission denied**: User declined notification permission
* **Invalid project ID**: Project ID doesn't start with `prj_` or is incorrect
* **Platform setup incomplete**: Missing Firebase configuration (Android) or iOS capabilities
* **Network issues**: Device can't connect to registration servers

**Solutions:**

* Verify project ID format: `prj_XXXXXXXXX`
* Test on physical devices (emulators may have permission issues)
* Check platform setup is complete (see Platform Setup guide)
* Retry registration after fixing setup issues
* Check device token using `PntaFlutter.deviceToken` getter after initialization

### Delayed registration issues

**Symptoms:** `registerDevice()` fails after `initialize(registerDevice: false)`

**Solutions:**

* Ensure `initialize()` was called first
* Check that platform setup is complete before calling `registerDevice()`
* Verify user hasn't manually disabled notifications in system settings

## 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`:**

```gradle android/build.gradle theme={null}
buildscript {
  dependencies {
    classpath 'com.google.gms:google-services:4.3.15'
  }
}
```

**App-level `android/app/build.gradle`:**

```gradle android/app/build.gradle theme={null}
// 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

## Notification Delivery Issues

### Notifications not received

**Symptoms:** Device registration successful but notifications don't arrive

**Solutions:**

* Verify device registration was successful: check `PntaFlutter.deviceToken` is not `null`
* Check PNTA project is configured correctly in dashboard
* Ensure Firebase setup is complete (Android)
* Test with a simple notification from PNTA dashboard
* Verify app is in background/terminated when testing (foreground notifications need custom handling)
* Check device notification settings haven't been disabled by user

## Setup and Configuration Issues

### Plugin initialization problems

**Symptoms:** `initialize()` throws errors or app crashes

**Solutions:**

* Call `WidgetsFlutterBinding.ensureInitialized()` before `initialize()`
* Ensure `initialize()` is awaited properly
* Verify project ID format is correct (`prj_XXXXXXXXX`)
* Check platform setup is complete before calling `initialize()`
* If using delayed registration, don't call other methods until after `registerDevice()`

## Getting Help

If you're still experiencing issues:

1. Check the [example app](https://github.com/pnta-io/pnta-flutter-plugin/tree/main/example) for a complete working implementation
2. Review your implementation against the [Quick Start Guide](/guides/flutter/quick-start)
3. Verify platform setup following the [Platform Setup Guide](/guides/flutter/platform-setup)
4. File an issue on the [GitHub repository](https://github.com/pnta-io/pnta-flutter-plugin/issues) with:
   * Flutter version (`flutter --version`)
   * Plugin version
   * Platform (iOS/Android)
   * Detailed error messages
   * Minimal reproduction code