Debugging

It's recommended that you wrap displayNotification and createTriggerNotification in a try/catch to catch any validation errors that may be thrown:

try {
  await notifee.displayNotification({
    title: 'Chat with Joe Bloggs',
    body: 'A new message has been received from a user.',
    ...
  });
} catch (e) {
  console.log(e);
}

Native Logs

Android

• Enable native logs in release mode by running:

adb shell setprop log.tag.NOTIFEE DEBUG

• To quickly view Android logs in the terminal:

adb logcat '*:S' NOTIFEE:D

CLI (init-nse)

The npx react-native-notify-kit init-nse command scaffolds an iOS Notification Service Extension. When it fails, the CLI rolls back .pbxproj and Podfile edits atomically. Common failure modes:

• "Could not locate the main app target's closing end in Podfile" — the Podfile has non-standard indentation or was edited by another tool. Inspect the Podfile manually and retry, or point the CLI at a clean copy with --ios-path.
• "Invalid --bundle-suffix" — the flag must match /^\.[A-Za-z0-9\-.]+$/ (starts with a dot, alphanumerics/dots/hyphens only). Spaces and other special characters are rejected to prevent .pbxproj corruption.
• Bundle ID contains unresolved Xcode variable — if your parent bundle ID uses $(PRODUCT_BUNDLE_PREFIX) or a similar variable the CLI cannot expand, the CLI logs a warning and proceeds with a placeholder. Fix the NSE bundle ID manually in Xcode after generation.
• Cycle inside <AppName> after adding NotifyKitNSE.appex — this usually involves React Native Firebase's [RNFB] Core Configuration build phase. Current init-nse versions add a Podfile post_install patch that removes the problematic RNFB input path after each pod install; rerun init-nse, then pod install, before editing RNFB build phases manually.

Run with --dry-run to preview the file changes without writing anything, or --force to overwrite an existing NSE target. See the FCM Mode guide for the full CLI reference.

FCM Mode logs

When you use the FCM Mode integration (see Firebase Cloud Messaging), a handful of diagnostic messages are emitted that are useful when troubleshooting missing attachments, missing payloads, or unexpected fallback behavior.

Client-side console.warn (from parseFcmPayload and reconstructNotification):

• Failed to parse notifee_options — the server payload is malformed JSON.
• notifee_options parsed to a non-object value — the blob decoded but isn't an object.
• notifee_options version X is newer than supported version 1 — the client is older than the server SDK that produced the payload.
• Failed to parse notifee_data — the notifee_data sibling is malformed.
• android.style.type '<type>' present but required '<field>' field missing — e.g. BIG_PICTURE without picture, or BIG_TEXT without text. The style is dropped.
• Unknown android.style.type '<type>' — the style isn't in AndroidStyle. The style is dropped.
• Unknown ios.interruptionLevel '<level>' — the iOS interruption level isn't in the supported set.
• ios.attachments entry has missing or empty url — the attachment is filtered out.

Server-side console.warn (from buildNotifyKitPayload):

• Payload size X bytes approaches FCM 4KB limit. Consider reducing notifee_options. — fires when the serialized payload exceeds ~3500 UTF-8 bytes.

iOS NSE logs (generated Swift template — visible in Console.app by filtering on the NotifyKitNSE process):

• [NotifyKitNSE] didReceive id=... — the NSE received a push.
• [NotifyKitNSE] contentHandler id=... — the NSE finished enriching and handed the content back to the OS.
• [NotifyKitNSE] serviceExtensionTimeWillExpire — the NSE ran out of its ~30 s budget (typical cause: slow attachment download on a weak network). The OS displays the un-enriched fallback.

One normal invocation emits two log lines (didReceive + contentHandler). The serviceExtensionTimeWillExpire line appears only on the timeout path.