axiom-core-location-diag

---
name: axiom-core-location-diag
description: "Use for Core Location troubleshooting - no location updates, background location broken, authorization denied, geofence not triggering"
---


# 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

## Red Flags

| Red Flag | Why It Bites | Fix |
|----------|--------------|-----|
| Requesting `.always` / `.authorizedAlways` on first launch | Up-front Always denial runs ~30-60%; When-In-Use then escalate runs ~5-10% (WWDC 2024-10212) | Request When In Use first, escalate to Always only when a feature needs it |
| Using a location with `horizontalAccuracy < 0` | Coordinate is INVALID — Apple docs: "latitude and longitude are invalid" | Discard: `guard loc.horizontalAccuracy >= 0 else { continue }` before using or computing distance |
| `horizontalAccuracy > ~100m` treated as a real position | WiFi/cell-only fix, not GPS — wrong distances | Wait for a tighter fix or surface "locating…" instead of a number |
| Deprecated `authorizationStatus()` / class method checked once at launch | Static, never reflects later grants/revocations | Read the instance `manager.authorizationStatus` inside `locationManagerDidChangeAuthorization(_:)` |
| `CLLocationManager` held in a local var | Deallocates at end of scope; no delegate callbacks ever fire | Store the manager in a property |
| No `launchOptions[.location]` handling | Background relaunch event is dropped — significant-change "doesn't wake the app" | Recreate manager + restart services in `didFinishLaunching` when the key is present |

## Related Skills

- `axiom-location (skills/core-location.md)` — Implementation patterns, decision trees
- `axiom-location (skills/core-location-ref.md)` — API reference, code examples
- `axiom-performance (skills/energy-diag.md)` — Battery drain from location
- `axiom-location (skills/mapkit-diag.md)` — For map-specific location display issues (Symptom 7)

---

## Symptom 1: Location Updates Never Arrive

### Quick Checks

```swift
// 1. Check authorization
let status = CLLocationManager().authorizationStatus
print("Authorization: \(status.rawValue)")
// 0=notDetermined, 1=restricted, 2=denied, 3=authorizedAlways, 4=authorizedWhenInUse

// 2. Check if location services enabled system-wide
print("Services enabled: \(CLLocationManager.locationServicesEnabled())")

// 3. Check accuracy authorization
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

```xml
<!-- Required for any location access -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>Your clear explanation here</string>

<!-- Required for Always authorization -->
<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

1. **Background mode capability**: Xcode → Signing & Capabilities → Background Modes → Location updates
2. **Info.plist**: Should have `UIBackgroundModes` with `location` value
3. **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: Was the app relaunched into the background for a queued event?
├─ launchOptions[.location] present → System woke you to deliver one event
│   CRITICAL: The event is delivered to the delegate, NOT in launchOptions.
│   If you don't recreate the manager + restart services synchronously in
│   didFinishLaunching, the queued event is DROPPED and the app sleeps again.
│   This is why significant-change "doesn't wake the app" — it does wake it,
│   but the relaunch handler never restarts monitoring. (See Relaunch Recovery below.)
│
└─ 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

```swift
// ❌ WRONG: Local variable deallocates immediately
func startTracking() {
    let session = CLBackgroundActivitySession()  // Dies at end of function!
    startLocationUpdates()
}

// ✅ RIGHT: Property keeps session alive
var backgroundSession: CLBackgroundActivitySession?

func startTracking() {
    backgroundSession = CLBackgroundActivitySession()
    startLocationUpdates()
}
```

#### Relaunch Recovery (required for significant-change and region monitoring)

When the system relaunches a terminated app to deliver a location event, the event
goes to the delegate — never the launch dictionary. If you don't recreate the manager
and restart services in `didFinishLaunching`, the queued event is dropped.

```swift
func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    if options?[.location] != nil {
        // Background relaunch for a queued event — recreate + restart NOW
        locationManager = makeConfiguredManager()        // store in a property
        locationManager.startMonitoringSignificantLocationChanges()
        // Restart whatever you were monitoring before termination
    }
    return true
}
```

---

## Symptom 3: Authorization Always Denied

### Authorization Strategy

Requesting `.always` on first launch is the single biggest cause of avoidable denials.
Apple's data (WWDC 2024-10212): an up-front Always prompt is denied ~30-60% of the time,
while requesting When In Use first and escalating to Always only when a feature needs it
lands ~5-10% denial. Asking for "Always everywhere" up front does not buy more access —
it loses access.

When a tech lead says "just request Always up front so we never have to ask again":
escalate the request, not the prompt. Take a When-In-Use `CLServiceSession` at launch,
then take an `.always` session the moment the user enables a background feature (geofence
reminder, trip logging). iOS shows the Always upgrade prompt in that context, where users
say yes far more often.

### 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

```xml
<!-- ❌ BAD: Vague, no value proposition -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location.</string>

<!-- ✅ GOOD: Specific benefit to user -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>Your location helps show restaurants, coffee shops, and attractions within walking distance.</string>

<!-- ❌ BAD: No explanation for Always -->
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We need your location always.</string>

<!-- ✅ GOOD: Explains background benefit -->
<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

```swift
// 1. Check accuracy authorization
let accuracy = CLLocationManager().accuracyAuthorization
print("Accuracy auth: \(accuracy == .fullAccuracy ? "full" : "reduced")")

// 2. Check update's accuracy flag (iOS 17+) and FILTER invalid fixes
for try await update in CLLocationUpdate.liveUpdates() {
    if update.accuracyLimited {
        print("Accuracy limited - updates every 15-20 min")
    }
    guard let location = update.location else { continue }

    // Hard filter: a negative accuracy means the coordinate is invalid.
    // Never compute distance or display a position from these.
    guard location.horizontalAccuracy >= 0 else { continue }

    // > ~100m is a WiFi/cell-only fix, not GPS — wrong distances
    if location.horizontalAccuracy > 100 {
        print("Coarse fix (\(location.horizontalAccuracy)m) — waiting for GPS")
    }
}
```

### 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?
├─ < 0 (typically -1) → INVALID location, do not use
│   Meaning: System could not determine accuracy (no valid fix)
│   Fix: Filter out: guard location.horizontalAccuracy >= 0 else { continue }
│   Common when: Indoors with no WiFi, airplane mode, immediately after cold start
│
├─ > 100m → Likely using WiFi/cell only (no GPS)
│   Causes: Indoors, airplane mode, dense urban canyon
│   Fix: User needs to move to better location, or wait for GPS lock
│
├─ 10-100m → Normal for most use cases
│   If need better: Use .automotiveNavigation or .otherNavigation config
│
└─ < 10m → Good GPS accuracy
    Note: .automotiveNavigation can achieve ~5m

Q3: What LiveConfiguration are you using?
├─ .default or none → System manages, may prioritize battery
│   If need more accuracy: Use .fitness, .otherNavigation, or .automotiveNavigation
│
├─ .fitness → Good for pedestrian activities
│
└─ .automotiveNavigation → Highest accuracy, highest battery
    Only use for actual navigation

Q4: Is the location stale?
├─ Check location.timestamp
│   If old: Device hasn't moved, or updates paused (isStationary)
│
└─ If timestamp recent but accuracy poor: Environmental issue
```

### Requesting Temporary Full Accuracy

Both paths require an `Info.plist` purpose dictionary. The dictionary key is
`NSLocationTemporaryUsageDescriptionDictionary`; each entry maps a purpose key
to a user-facing string:

```xml
<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
    <key>NavigationPurpose</key>
    <string>Precise location enables turn-by-turn directions.</string>
</dict>
```

```swift
// Declarative (iOS 18+): hold the session while the feature is active
let session = CLServiceSession(
    authorization: .whenInUse,
    fullAccuracyPurposeKey: "NavigationPurpose"
)

// Imperative (iOS 14+): for code still on CLLocationManager
manager.requestTemporaryFullAccuracyAuthorization(withPurposeKey: "NavigationPurpose")
```

---

## Symptom 5: Geofence Events Not Triggering

### Quick Checks

```swift
let monitor = await CLMonitor("MyMonitor")

// 1. Check condition count (max 20)
let count = await monitor.identifiers.count
print("Conditions: \(count)/20")

// 2. Check specific condition
if let record = await monitor.record(for: "MyGeofence") {
    let lastEvent = record.lastEvent
    print("State: \(lastEvent.state)")
    print("Date: \(lastEvent.date)")

    if let geo = record.condition as? CLMonitor.CircularGeographicCondition {
        print("Center: \(geo.center)")
        print("Radius: \(geo.radius)m")
    }
}
```

### Decision Tree

```
Q1: How many conditions are monitored?
├─ 20 → At the limit, new conditions ignored
│   Fix: Prioritize important conditions, swap dynamically based on user location
│   Check: lastEvent.conditionLimitExceeded
│
└─ < 20 → Check next

Q2: What is the radius?
├─ < 100m → Unreliable, may not trigger
│   Fix: Use minimum 100m radius for reliable detection
│
└─ >= 100m → Check next

Q3: Is the app awaiting monitor.events?
├─ NO → Events not processed, lastEvent not updated
│   Fix: Always have a Task awaiting:
│        for try await event in monitor.events { ... }
│
└─ YES → Check next

Q4: Was monitor reinitialized on app launch?
├─ NO → Monitor conditions lost after termination
│   Fix: Recreate monitor with same name in didFinishLaunchingWithOptions
│
└─ YES → Check next

Q5: What does lastEvent show?
├─ state: .unknown → System hasn't determined state yet
│   Wait for determination, or check if monitoring is working
│
├─ state: .satisfied → Inside region, waiting for exit
│
├─ state: .unsatisfied → Outside region, waiting for entry
│
└─ Check lastEvent.date → When was last update?
    If very old: May not be monitoring correctly

Q6: Is accuracyLimited preventing monitoring?
├─ Check: lastEvent.accuracyLimited
│   If true: Reduced accuracy prevents geofencing
│   Fix: Request full accuracy or accept limitation
│
└─ NO → Check environment (device must have location access)
```

### Common Mistakes

```swift
// ❌ WRONG: Not awaiting events
let monitor = await CLMonitor("Test")
await monitor.add(condition, identifier: "Place")
// Nothing happens - no Task awaiting events!

// ✅ RIGHT: Always await events
let monitor = await CLMonitor("Test")
await monitor.add(condition, identifier: "Place")

Task {
    for try await event in monitor.events {
        switch event.state {
        case .satisfied: handleEntry(event.identifier)
        case .unsatisfied: handleExit(event.identifier)
        case .unknown: break
        @unknown default: break
        }
    }
}

// ❌ WRONG: Creating multiple monitors with same name
let monitor1 = await CLMonitor("App")  // OK
let monitor2 = await CLMonitor("App")  // UNDEFINED BEHAVIOR

// ✅ RIGHT: One monitor instance per name
class LocationService {
    private var monitor: CLMonitor?

    func setup() async {
        monitor = await CLMonitor("App")
    }
}
```

---

## Symptom 6: Location Icon Won't Go Away

### Quick Checks

The location arrow appears when:
- App actively receiving location updates
- CLMonitor is monitoring conditions
- Background activity session active

### Decision Tree

```
Q1: Is your app still iterating liveUpdates?
├─ YES → Updates continue until you break/cancel
│   Fix: Cancel the Task or break from loop:
│        locationTask?.cancel()
│
└─ NO → Check next

Q2: Is CLBackgroundActivitySession still held?
├─ YES → Session keeps location access active
│   Fix: Invalidate when done:
│        backgroundSession?.invalidate()
│        backgroundSession = nil
│
└─ NO → Check next

Q3: Is CLMonitor still monitoring conditions?
├─ YES → CLMonitor uses location for geofencing
│   Note: This is expected behavior - icon shows monitoring active
│   Fix: If truly done, remove all conditions:
│        for id in await monitor.identifiers {
│            await monitor.remove(id)
│        }
│
└─ NO → Check next

Q4: Is legacy CLLocationManager still running?
├─ Check: manager.stopUpdatingLocation() called?
│   Check: manager.stopMonitoring(for: region) for all regions?
│   Fix: Ensure all legacy APIs stopped
│
└─ NO → Check other location-using frameworks

Q5: Other frameworks using location?
├─ MapKit with showsUserLocation = true → Shows location
│   Fix: mapView.showsUserLocation = false when not needed
│
├─ Core Motion with location → Shows location
│
└─ Check all location-using code
```

### Force Stop All Location

```swift
// Stop modern APIs
locationTask?.cancel()
backgroundSession?.invalidate()
backgroundSession = nil

// Remove all CLMonitor conditions
for id in await monitor.identifiers {
    await monitor.remove(id)
}

// Stop legacy APIs
manager.stopUpdatingLocation()
manager.stopMonitoringSignificantLocationChanges()
manager.stopMonitoringVisits()

for region in manager.monitoredRegions {
    manager.stopMonitoring(for: region)
}
```

---

## Console Debugging

### Filter Location Logs

```bash
# View locationd logs
log stream --predicate 'subsystem == "com.apple.locationd"' --level debug

# View your app's location-related logs
log stream --predicate 'subsystem == "com.apple.CoreLocation"' --level debug

# Filter for specific process
log stream --predicate 'process == "YourAppName" AND subsystem == "com.apple.CoreLocation"'
```

### Common Log Messages

| Log Message | Meaning |
|-------------|---------|
| `Client is not authorized` | Authorization denied or not requested |
| `Location services disabled` | System-wide toggle off |
| `Accuracy authorization is reduced` | User chose approximate location |
| `Condition limit exceeded` | At 20-condition maximum |
| `Background location access denied` | Missing background capability or session |

---

## Resources

**WWDC**: 2023-10180, 2023-10147, 2024-10212

**Docs**: /corelocation, /corelocation/clmonitor, /corelocation/cllocationupdate

**Skills**: axiom-location (skills/core-location.md), axiom-location (skills/core-location-ref.md), axiom-performance (skills/energy-diag.md)