Core Location Diagnostics
Symptom-based troubleshooting for Core Location issues.
When to Use
- Location updates never arrive
- Background location stops working
- Authorization always denied
- Location accuracy unexpectedly poor
- Geofence events not triggering
- Location icon won't go away
Related Skills
axiom-core-location — Implementation patterns, decision treesaxiom-core-location-ref — API reference, code examplesaxiom-energy-diag — Battery drain from locationaxiom-mapkit-diag — For map-specific location display issues (Symptom 7)
Symptom 1: Location Updates Never Arrive
Quick Checks
let status = CLLocationManager().authorizationStatus
print("Authorization: \(status.rawValue)")
print("Services enabled: \(CLLocationManager.locationServicesEnabled())")
let accuracy = CLLocationManager().accuracyAuthorization
print("Accuracy: \(accuracy == .fullAccuracy ? "full" : "reduced")")
Decision Tree
Q1: What does authorizationStatus return?
├─ .notDetermined → Authorization never requested
│ Fix: Add CLServiceSession(authorization: .whenInUse) or requestWhenInUseAuthorization()
│
├─ .denied → User denied access
│ Fix: Show UI explaining why location needed, link to Settings
│
├─ .restricted → Parental controls block access
│ Fix: Inform user, offer manual location input
│
└─ .authorizedWhenInUse / .authorizedAlways → Check next
Q2: Is locationServicesEnabled() returning true?
├─ NO → Location services disabled system-wide
│ Fix: Show UI prompting user to enable in Settings → Privacy → Location Services
│
└─ YES → Check next
Q3: Are you iterating the AsyncSequence?
├─ NO → Updates only arrive when you await
│ Fix: Task { for try await update in CLLocationUpdate.liveUpdates() { ... } }
│
└─ YES → Check next
Q4: Is the Task cancelled or broken?
├─ YES → Task cancelled before updates arrived
│ Fix: Ensure Task lives long enough (store in property, not local)
│
└─ NO → Check next
Q5: Is location available? (iOS 17+)
├─ Check update.locationUnavailable
│ If true: Device cannot determine location (indoors, airplane mode, no GPS)
│ Fix: Wait or inform user to move to better location
│
└─ Check update.authorizationDenied / update.authorizationDeniedGlobally
If true: Handle denial gracefully
Info.plist Checklist
<key>NSLocationWhenInUseUsageDescription</key>
<string>Your clear explanation here</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Your clear explanation here</string>
Missing these keys = silent failure with no prompt.
Symptom 2: Background Location Not Working
Quick Checks
- Background mode capability: Xcode → Signing & Capabilities → Background Modes → Location updates
- Info.plist: Should have
UIBackgroundModes with location value
- CLBackgroundActivitySession: Must be created AND held
Decision Tree
Q1: Is "Location updates" checked in Background Modes?
├─ NO → Background location silently disabled
│ Fix: Xcode → Signing & Capabilities → Background Modes → Location updates
│
└─ YES → Check next
Q2: Are you holding CLBackgroundActivitySession?
├─ NO / Using local variable → Session deallocates, background stops
│ Fix: Store in property: var backgroundSession: CLBackgroundActivitySession?
│
└─ YES → Check next
Q3: Was session started from foreground?
├─ NO → Cannot start new session from background
│ Fix: Create CLBackgroundActivitySession while app in foreground
│
└─ YES → Check next
Q4: Is app being terminated and not recovering?
├─ YES → Not recreating session on relaunch
│ Fix: In didFinishLaunchingWithOptions:
│ if wasTrackingLocation {
│ backgroundSession = CLBackgroundActivitySession()
│ startLocationUpdates()
│ }
│
└─ NO → Check authorization level
Q5: What is authorization level?
├─ .authorizedWhenInUse → This is fine with CLBackgroundActivitySession
│ The blue indicator allows background access
│
├─ .authorizedAlways → Should work, check session lifecycle
│
└─ .denied → No background access possible
Common Mistakes
func startTracking() {
let session = CLBackgroundActivitySession()
startLocationUpdates()
}
var backgroundSession: CLBackgroundActivitySession?
func startTracking() {
backgroundSession = CLBackgroundActivitySession()
startLocationUpdates()
}
Symptom 3: Authorization Always Denied
Decision Tree
Q1: Is this a fresh install or returning user?
├─ FRESH INSTALL with immediate denial → Check Info.plist strings
│ Missing/empty NSLocationWhenInUseUsageDescription = automatic denial
│
└─ RETURNING USER → Check previous denial
Q2: Did user previously deny?
├─ YES → User must manually re-enable in Settings
│ Fix: Show UI explaining value, with button to open Settings:
│ UIApplication.shared.open(URL(string: UIApplication.openSettingsURLString)!)
│
└─ NO → Check next
Q3: Are you requesting authorization at wrong time?
├─ Requesting when app not "in use" → insufficientlyInUse
│ Check: update.insufficientlyInUse or diagnostic.insufficientlyInUse
│ Fix: Only request authorization from foreground, during user interaction
│
└─ NO → Check next
Q4: Is device in restricted mode?
├─ YES → .restricted status (parental controls, MDM)
│ Fix: Cannot override. Offer manual location input.
│
└─ NO → Check Info.plist again
Q5: Are Info.plist strings compelling?
├─ Generic string → Users more likely to deny
│ Bad: "This app needs your location"
│ Good: "Your location helps us show restaurants within walking distance"
│
└─ Review: Look at string from user's perspective
Info.plist String Best Practices
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Your location helps show restaurants, coffee shops, and attractions within walking distance.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We need your location always.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Enable background location to receive reminders when you arrive at saved places, even when the app is closed.</string>
Symptom 4: Location Accuracy Unexpectedly Poor
Quick Checks
let accuracy = CLLocationManager().accuracyAuthorization
print("Accuracy auth: \(accuracy == .fullAccuracy ? "full" : "reduced")")
for try await update in CLLocationUpdate.liveUpdates() {
if update.accuracyLimited {
print("Accuracy limited - updates every 15-20 min")
}
if let location = update.location {
print("Horizontal accuracy: \(location.horizontalAccuracy)m")
}
}
Decision Tree
Q1: What is accuracyAuthorization?
├─ .reducedAccuracy → User chose approximate location
│ Options:
│ 1. Accept reduced accuracy (weather, city-level features)
│ 2. Request temporary full accuracy:
│ CLServiceSession(authorization: .whenInUse, fullAccuracyPurposeKey: "Navigation")
│ 3. Explain value and link to Settings
│
└─ .fullAccuracy → Check environment and configuration
Q2: What is horizontalAccuracy on locations?
