axiom-background-processing-diag

Background Processing Diagnostics

Symptom-based troubleshooting for background task issues.

Related skills: axiom-background-processing (patterns, checklists), axiom-background-processing-ref (API reference)

---

Symptom 1: Task Never Runs

Handler never called despite successful submit().

Quick Diagnosis (5 minutes)

Task never runs?
│
├─ Step 1: Check Info.plist (2 min)
│  ├─ BGTaskSchedulerPermittedIdentifiers contains EXACT identifier?
│  │  └─ NO → Add identifier, rebuild
│  ├─ UIBackgroundModes includes "fetch" or "processing"?
│  │  └─ NO → Add required mode
│  └─ Identifiers case-sensitive match code?
│     └─ NO → Fix typo, rebuild
│
├─ Step 2: Check registration timing (2 min)
│  ├─ Registered in didFinishLaunchingWithOptions?
│  │  └─ NO → Move registration before return true
│  └─ Registration before first submit()?
│     └─ NO → Ensure register() precedes submit()
│
└─ Step 3: Check app state (1 min)
   ├─ App swiped away from App Switcher?
   │  └─ YES → No background until user opens app
   └─ Background App Refresh disabled in Settings?
      └─ YES → Enable or inform user

Time-Cost Analysis

Approach	Time	Success Rate
Check Info.plist + registration	5 min	70% (catches most issues)
Add console logging	15 min	90%
LLDB simulate launch	5 min	95% (confirms handler works)
Random code changes	2+ hours	Low

LLDB Quick Test

Verify handler is correctly registered:

e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.yourapp.refresh"]

If breakpoint hits → Registration correct, issue is scheduling/system factors. If nothing happens → Registration broken.

---

Symptom 2: Task Terminates Unexpectedly

Handler called but work doesn't complete before termination.

Quick Diagnosis (5 minutes)

Task terminates early?
│
├─ Step 1: Check expiration handler (1 min)
│  ├─ Expiration handler set FIRST in handler?
│  │  └─ NO → Move to very first line
│  └─ Expiration handler actually cancels work?
│     └─ NO → Add cancellation logic
│
├─ Step 2: Check setTaskCompleted (2 min)
│  ├─ Called in success path?
│  ├─ Called in failure path?
│  ├─ Called after expiration?
│  └─ ANY path missing → Task never signals completion
│
├─ Step 3: Check work duration (2 min)
│  ├─ BGAppRefreshTask work > 30 seconds?
│  │  └─ YES → Chunk work or use BGProcessingTask
│  └─ BGProcessingTask work > system limit?
│     └─ YES → Save progress, resume on next launch