sojorn/sojorn_docs/features/notifications-troubleshooting.md

Notifications Troubleshooting (Go Backend)

Note

: This document has been updated for the 100% Go backend migration. Legacy Supabase edge function references are no longer applicable.

Current Architecture

All notification APIs now use the Go backend with JWT authentication:

• Register Token: POST /api/v1/notifications/device
• Unregister Token: DELETE /api/v1/notifications/device
• Get Notifications: GET /api/v1/notifications

Authentication uses Authorization: Bearer <token> header with Go-issued JWTs.

---

Common Issues

1. Token Not Syncing to Backend

Symptoms:

• FCM token obtained successfully but not stored in database
• Debug logs show [FCM] Token synced with Go Backend successfully not appearing

Solutions:

1. Verify user is authenticated before calling NotificationService.init()
2. Check API endpoint responds (network tab / logs)
3. Ensure JWT token is valid and not expired

2. Push Notifications Not Received

Symptoms:

• Token exists in database
• No push received on device

Diagnosis:

-- Check if token exists for user
SELECT * FROM user_fcm_tokens WHERE user_id = 'your-uuid';

Solutions:

1. Verify FIREBASE_CREDENTIALS_FILE path is correct in backend .env
2. Check Firebase Console for delivery reports
3. For web, verify FIREBASE_WEB_VAPID_KEY matches Firebase Console
4. On Android 13+, check POST_NOTIFICATIONS permission granted

3. Android 13+ Permission Denied

Symptoms:

• [FCM] Android notification permission not granted: denied

Solution: The app now properly requests POST_NOTIFICATIONS at runtime. If user denied:

1. Guide them to Settings > Apps > Sojorn > Notifications
2. Enable notifications manually

4. Web Push Not Working

Symptoms:

• Token is null on web platform
• [FCM] Web push is missing FIREBASE_WEB_VAPID_KEY

Solutions:

1. Verify VAPID key in lib/config/firebase_web_config.dart
2. Key must match Firebase Console > Cloud Messaging > Web Push certificates
3. Must be served over HTTPS (except localhost)

5. Duplicate Tokens in Database

The schema now has a unique constraint on (user_id, token):

UNIQUE(user_id, token)

This prevents duplicates via upsert logic:

ON CONFLICT (user_id, token) DO UPDATE SET last_updated = ...

---

Logout Cleanup

On logout, the Flutter client now:

1. Calls backend to delete token from user_fcm_tokens
2. Deletes token from Firebase locally via deleteToken()
3. Resets initialization state

This ensures the device no longer receives notifications for the logged-out user.

---

Testing Checklist

• Token registration works on Android
• Token registration works on Web
• Token appears in user_fcm_tokens table with correct device_type
• New message triggers push to recipient
• Post save triggers push to author
• Comment triggers push to post author
• Follow triggers push to followed user
• Tapping notification navigates correctly
• Logout removes token from database
• Re-login registers new token

---

Related Documentation

• FCM Implementation Guide - Complete implementation details
• Backend API Documentation - All API endpoints