So you’ve set up your self-hosted AirNotifier instance, perhaps by following our beginner’s guide or using the Docker installation method. You send your first test push notification, and… nothing happens. Or worse, you get a cryptic error message in the logs. Don’t worry, you’re not alone.
AirNotifier is a powerful tool, but like any system, it has common points of failure. This guide will walk you through the most frequent errors and provide clear, step-by-step solutions to get your notifications flowing correctly.
Error 1: InvalidDeviceToken or NotRegistered
This is by far the most common error. You try to send a notification, and the log shows that the device token is invalid or no longer registered with the push notification service (Apple’s APNs or Google’s FCM).
Root Causes and Solutions
- The User Uninstalled the App: This is the most frequent cause. When a user uninstalls your application, the push token associated with that installation becomes invalid. Both APNs and FCM will report it as stale.
- Solution: Your system must have a feedback loop. When you receive an InvalidDeviceToken or NotRegistered error, you must delete that token from your database. Continuously trying to send to a dead token can get your server temporarily blocked by the push gateways for causing unnecessary traffic.
- Mismatched Environments (iOS/APNs): You are trying to send a notification to a production device token using a development/sandbox certificate, or vice-versa.
- Solution: In AirNotifier, ensure you have configured both a sandbox and a production app profile. Your mobile application should send a flag indicating which environment it’s running in, so your backend knows which AirNotifier app ID (and corresponding certificate) to use.
- Incorrect Token Format: The token was copied incorrectly or corrupted when being sent from the device to your server.
- Solution: Log the tokens you receive on your server and compare them with the tokens generated on the device. Ensure there are no encoding issues or accidental truncations.
Error 2: Connection Timeouts or SSL/TLS Handshake Failures (APNs)
You try to send a notification to an iOS device, but the AirNotifier log shows a connection timeout or an SSL error when trying to connect to Apple’s servers.
Root Causes and Solutions
- Firewall Issues: This is the number one cause. Apple’s push notification service requires specific network ports to be open for outbound connections. Your server’s firewall may be blocking them.
- Solution: Ensure that your server’s firewall allows outbound TCP connections on port 443 and port 2197. According to Apple’s official documentation, these ports are essential for communication with APNs.
- Expired or Invalid APNs Certificate: The .pem certificate you uploaded to AirNotifier has expired, has been revoked, or was not generated correctly.
- Solution: Log in to your Apple Developer account and check the validity of your push notification certificate. Generate a new one if needed, convert it to the .pem format (certificate and private key combined), and re-upload it to the correct application profile in AirNotifier.
Error 3: AuthenticationError or 401 Unauthorised (FCM)
When sending to Android devices, you see an authentication error in the logs. This means Google’s servers are rejecting your requests.
Root Causes and Solutions
- Incorrect FCM Server Key: The API key you entered into AirNotifier for your Android application is incorrect or has been revoked.
- Solution: Go to your Firebase Console, select your project, and navigate to Project Settings > Cloud Messaging. Here you will find your Server Key. Copy it carefully and paste it into the “API Key” field for your app in AirNotifier.
- FCM API Not Enabled: In some Google Cloud Projects, the Firebase Cloud Messaging API may be disabled by default.
- Solution: Go to your Google Cloud Console, navigate to the “APIs & Services” dashboard, and ensure that the “Firebase Cloud Messaging API” is enabled for your project.
General Troubleshooting Steps
If you’re still stuck, follow this checklist. Many developers on platforms like Stack Overflow have solved their issues by systematically checking these points.
- Check your AirNotifier Logs: The airnotifier.log file is your best friend. Set the logging level to DEBUG in your airnotifier.conf for more detailed output.
- Verify App IDs and Profiles: Double-check that you are sending the notification to the correct app_id that corresponds to the right platform (iOS/Android) and environment (sandbox/production).
- Test with a Single, Known-Good Device: Hardcode a specific, recently generated device token and try to send a notification directly to it. This isolates the problem from any database or token-fetching issues.
- Isolate the Network: From the server running AirNotifier, use command-line tools like curl or openssl s_client to try and connect to the APNs/FCM gateways directly. This will tell you if you have a network or firewall problem.
Still Stuck? Let Our Experts Take a Look.
Troubleshooting distributed systems can be complex. If you’ve gone through this guide and are still facing issues, it might be a sign of a deeper problem with your configuration, network, or architecture.
Our team has deep expertise in building and managing robust notification systems. We can help you diagnose the problem and build a reliable solution that just works.
