Push Notification Diagnostics

Systematic troubleshooting for push notification failures: missing notifications, token registration errors, environment mismatches, silent push throttling, and service extension problems.

Overview

Core Principle: When push notifications don't work, the problem is usually:

1. Token/registration failures (never registered, wrong format, expired) — 30%
2. Entitlement/provisioning mismatch (capability missing, wrong environment) — 25%
3. Payload structure errors (missing keys, wrong types, invalid JSON) — 15%
4. Focus/interruption suppression (iOS 15+ filtering, provisional auth) — 15%
5. Service extension failures (timeout, crash, missing mutable-content) — 10%
6. Delivery timing/throttling (silent push budget, APNs coalescing) — 5%

Always verify entitlements and token registration BEFORE debugging payload or delivery logic.

Red Flags

Symptoms that indicate push-specific issues: