---
name: axiom-mapkit-diag
description: MapKit troubleshooting — annotations not appearing, region jumping, clustering not working, search failures, overlay rendering issues, user location problems
license: MIT
metadata:
  version: "1.0.0"
  last-updated: "2026-02-26"
---

# MapKit Diagnostics

Symptom-based MapKit troubleshooting. Start with the symptom you're seeing, follow the diagnostic path.

## Related Skills

- `axiom-mapkit` — Patterns, decision trees, anti-patterns
- `axiom-mapkit-ref` — API reference, code examples

---

## Quick Reference

| Symptom | Check First | Common Fix |
|---|---|---|
| Annotations not appearing | Coordinate values (lat/lng swapped?) | Verify coordinate, check viewFor delegate |
| Map region jumps/loops | updateUIView guard | Add region equality check |
| Slow with many annotations | Annotation count, view reuse | Enable clustering, implement view reuse |
| Clustering not working | clusteringIdentifier set? | Set same identifier on all views |
| Overlays not rendering | renderer delegate method | Return correct MKOverlayRenderer subclass |
| Search returns no results | resultTypes, region bias | Set appropriate resultTypes and region |
| User location not showing | Authorization status | Request CLLocationManager authorization first |
| Coordinates appear wrong | lat/lng order | MapKit uses (latitude, longitude) — verify data source |

---

## Symptom 1: Annotations Not Appearing

### Decision Tree

```
Q1: Are coordinates valid?
├─ 0,0 or NaN → Data source returning default/empty values
│   Fix: Validate coordinates before adding annotations
│   Debug: print("\(annotation.coordinate.latitude), \(annotation.coordinate.longitude)")
│
└─ Valid numbers → Check next

Q2: Are lat/lng swapped?
├─ YES (common with GeoJSON which uses [longitude, latitude]) → Swap values
│   GeoJSON: [lng, lat] — MapKit: CLLocationCoordinate2D(latitude:, longitude:)
│   Fix: CLLocationCoordinate2D(latitude: json[1], longitude: json[0])
│
└─ NO → Check next

Q3: (MKMapView) Is mapView(_:viewFor:) delegate returning nil for your annotations?
├─ Not implemented → System uses default pin (should appear)
├─ Returns nil → System uses default pin (should appear)
├─ Returns wrong view → Check implementation
│
└─ Check delegate is set

Q4: (MKMapView) Is delegate set?
├─ NO → mapView.delegate = self (or context.coordinator in UIViewRepresentable)
│   Without delegate: default pins appear. But if viewFor returns nil, check annotation type
│
└─ YES → Check next

Q5: (SwiftUI) Are annotations in Map content builder?
├─ NO → Annotations must be inside Map { ... } content closure
│   Fix: Map(position: $pos) { Marker("Name", coordinate: coord) }
│
└─ YES → Check next

Q6: Is the map region showing the annotation coordinates?
├─ Map centered elsewhere → Adjust camera/region to include annotation coordinates
│   Debug: Compare mapView.region with annotation coordinates
│   Fix: Use .automatic camera position or set region to fit annotations
│
└─ Region includes annotations → Check displayPriority

Q7: (MKMapView) Is displayPriority too low?
├─ .defaultLow → System may hide annotations at certain zoom levels
│   Fix: view.displayPriority = .required for must-show annotations
│
└─ .required → Annotation should appear — file a bug report with minimal repro
```

---

## Symptom 2: Map Region Jumping / Infinite Loops

### Decision Tree

```
Q1: (UIViewRepresentable) Is setRegion called in updateUIView without guard?
├─ YES → Classic infinite loop:
│   1. SwiftUI state changes → updateUIView called
│   2. updateUIView calls setRegion
│   3. setRegion triggers regionDidChangeAnimated delegate
│   4. Delegate updates SwiftUI state → back to step 1
│
│   Fix: Guard against unnecessary updates
│   if mapView.region.center.latitude != region.center.latitude
│      || mapView.region.center.longitude != region.center.longitude {
│       mapView.setRegion(region, animated: true)
│   }
│
│   Alternative: Use a flag in coordinator
│   coordinator.isUpdating = true
│   mapView.setRegion(region, animated: true)
│   coordinator.isUpdating = false
│   // In regionDidChangeAnimated: guard !isUpdating
│
└─ NO → Check next

Q2: Are multiple state sources fighting over the region?
├─ YES → Two bindings or state variables controlling the same region
│   Fix: Single source of truth for camera position
│   One @State var cameraPosition, not two conflicting values
│
└─ NO → Check next

Q3: (SwiftUI) Is MapCameraPosition properly bound?
├─ Using .constant() or recreating position on each render → Camera resets
│   Fix: @State private var cameraPosition: MapCameraPosition = .automatic
│   Use the binding: Map(position: $cameraPosition)
│
└─ Properly bound → Check next

Q4: Animation conflict?
├─ Using animated: true in updateUIView alongside SwiftUI animations → Double animation
│   Fix: Avoid animated: true in updateUIView, or disable SwiftUI animation for map
│
└─ NO → Check next

Q5: Is onMapCameraChange triggering state updates that move the camera?
├─ YES → Camera change → callback → state change → camera change
│   Fix: Only update non-camera state in the callback
│   Don't set cameraPosition inside onMapCameraChange
│
└─ NO → Check delegate implementation for unintended state mutations
```

---

## Symptom 3: Performance Issues

### Decision Tree

```
Q1: How many annotations?
├─ > 500 without clustering → Enable clustering
│   SwiftUI: .mapItemClusteringIdentifier("poi")
│   MKMapView: view.clusteringIdentifier = "poi"
│
├─ > 1000 → Consider visible-region filtering
│   Only load annotations within mapView.region
│   Use .onMapCameraChange to fetch when user scrolls
│
└─ < 500 → Check next

Q2: (MKMapView) Using dequeueReusableAnnotationView?
├─ NO → Every annotation creates a new view → memory spike
│   Fix: Register view class and dequeue in delegate
│   mapView.register(MKMarkerAnnotationView.self, forAnnotationViewWithReuseIdentifier: "marker")
│
└─ YES → Check next

Q3: Complex custom annotation views?
├─ YES → Rich SwiftUI views or complex UIViews per annotation
│   Fix: Pre-render to UIImage for MKAnnotationView.image
│   Or simplify to MKMarkerAnnotationView with glyph
│
└─ NO → Check next

Q4: Overlays with many coordinates?
├─ YES → Polylines/polygons with 10K+ points
│   Fix: Simplify geometry (Douglas-Peucker algorithm)
│   Or render at reduced detail for zoomed-out views
│
└─ NO → Check next

Q5: Geocoding in a loop?
├─ YES → CLGeocoder has rate limit (~1/second)
│   Fix: Batch geocoding, throttle requests, cache results
│   Use MKLocalSearch for batch lookups instead of per-item geocoding
│
└─ NO → Profile with Instruments → Time Profiler for CPU, Allocations for memory
```

---

## Symptom 4: Clustering Not Working

### Decision Tree

```
Q1: Is clusteringIdentifier set on annotation views?
├─ NO → Clustering requires an identifier on each annotation view
│   MKMapView: view.clusteringIdentifier = "poi" in viewFor delegate
│   SwiftUI: .mapItemClusteringIdentifier("poi") on content
│
└─ YES → Check next

Q2: Are ALL relevant views using the SAME identifier?
├─ NO → Different identifiers = different cluster groups
│   Fix: Use consistent identifier for annotations that should cluster together
│
└─ YES → Check next

Q3: (MKMapView) Is mapView(_:clusterAnnotationForMemberAnnotations:) needed?
├─ Not implemented → System creates default cluster
│   If you need custom cluster appearance, implement this delegate method
│
└─ Implemented → Check return value

Q4: Too few annotations in visible area?
├─ YES → Clustering only activates when annotations physically overlap
│   At low zoom (city level), 10 annotations might cluster
│   At high zoom (street level), same 10 might all be visible individually
│
└─ NO → Check next

Q5: (MKMapView) Are annotation views registered?
├─ NO → Register both individual and cluster view classes
│   mapView.register(MKMarkerAnnotationView.self, forAnnotationViewWithReuseIdentifier: "marker")
│
└─ YES → Verify viewFor delegate handles both MKClusterAnnotation and individual annotations
```

---

## Symptom 5: Overlays Not Rendering

### Decision Tree

```
Q1: (MKMapView) Is mapView(_:rendererFor:) delegate method implemented?
├─ NO → Overlays require a renderer — without this delegate method, nothing renders
│   Fix: Implement the delegate method, return appropriate renderer subclass
│
└─ YES → Check next

Q2: Is the correct renderer subclass returned?
├─ MKCircle → MKCircleRenderer
│   MKPolyline → MKPolylineRenderer
│   MKPolygon → MKPolygonRenderer
│   MKTileOverlay → MKTileOverlayRenderer
│   Mismatch → Crash or silent failure
│
└─ Correct → Check next

Q3: Is renderer styled?
├─ No strokeColor/fillColor/lineWidth set → Renderer exists but invisible
│   Fix: Set at minimum strokeColor and lineWidth
│   renderer.strokeColor = .systemBlue
│   renderer.lineWidth = 2
│
└─ Styled → Check next

Q4: Overlay level wrong?
├─ .aboveRoads → Overlay may be behind labels (hard to see)
│   Try: mapView.addOverlay(overlay, level: .aboveLabels)
│
└─ Check overlay coordinates match visible region

Q5: (SwiftUI) Using MapCircle/MapPolyline without styling?
├─ No .foregroundStyle or .stroke → May render transparent
│   Fix: MapCircle(center: coord, radius: 500)
│            .foregroundStyle(.blue.opacity(0.3))
│            .stroke(.blue, lineWidth: 2)
│
└─ Styled → Check coordinates are within visible map region
```

---

## Symptom 6: Search / Directions Failures

### Decision Tree

```
Q1: Network available?
├─ NO → MapKit search requires network connectivity
│   Fix: Check URLSession connectivity or NWPathMonitor
│
└─ YES → Check next

Q2: resultTypes too restrictive?
├─ Only .physicalFeature but searching for "Starbucks" → No results
│   Fix: Use .pointOfInterest for businesses, .address for streets
│   Or combine: [.pointOfInterest, .address]
│
└─ Appropriate → Check next

Q3: Region bias missing?
├─ NO region set → Results may be from anywhere in the world
│   Fix: request.region = mapView.region (or visible region)
│   This biases results to what the user can see
│
└─ Region set → Check next

Q4: Natural language query format?
├─ Structured format (lat/lng, codes) → Won't parse
│   Good: "coffee shops near San Francisco"
│   Good: "123 Main St"
│   Bad: "lat:37.7 lng:-122.4 coffee"
│   Bad: "POI_TYPE=cafe"
│
└─ Natural language → Check next

Q5: Rate limited?
├─ Getting errors after many requests → Apple rate-limits MapKit search
│   Fix: Throttle searches, use MKLocalSearchCompleter for autocomplete
│   Don't fire MKLocalSearch on every keystroke
│
└─ NO → Check next

Q6: (Directions) Source and destination valid?
├─ source or destination is nil → Request will fail
│   Fix: Verify both are valid MKMapItem instances
│   MKMapItem.forCurrentLocation() requires location authorization
│
└─ Both valid → Check transportType availability
    Transit directions not available in all regions
    Walking/driving available globally
```

---

## Symptom 7: User Location Not Showing

### Decision Tree

```
Q1: What is CLLocationManager.authorizationStatus?
├─ .notDetermined → Authorization never requested
│   Fix: Request authorization first, then enable user location
│   CLServiceSession(authorization: .whenInUse)
│
├─ .denied → User denied location access
│   Fix: Show UI explaining value, link to Settings
│
├─ .restricted → Parental controls block access
│   Fix: Inform user, cannot override
│
└─ .authorizedWhenInUse / .authorizedAlways → Check next

Q2: (MKMapView) Is showsUserLocation set to true?
├─ NO → mapView.showsUserLocation = true
│
└─ YES → Check next

Q3: (SwiftUI) Using UserAnnotation() in Map content?
├─ NO → Add UserAnnotation() inside Map { ... }
│
└─ YES → Check next

Q4: Running in Simulator?
├─ YES, no custom location set → Simulator doesn't have GPS
│   Fix: Debug menu → Location → Custom Location (or Apple/City Bicycle Ride/etc.)
│   Xcode: Debug → Simulate Location → pick a location
│
└─ Physical device → Check next

Q5: MapKit implicitly requests authorization — was it previously denied?
├─ MapKit shows no prompt if already denied
│   Check: Settings → Privacy & Security → Location Services → Your App
│   If "Never": User must manually re-enable
│
└─ Authorized → Check if location services enabled system-wide
    Settings → Privacy & Security → Location Services → toggle at top

Q6: Location icon appearing but blue dot not on screen?
├─ User is outside the visible map region
│   Fix: Use MapCameraPosition.userLocation(fallback: .automatic)
│   Or add MapUserLocationButton() in .mapControls
│
└─ See axiom-core-location-diag for deeper location troubleshooting
```

---

## Symptom 8: Coordinate System Confusion

Common coordinate mistakes that cause annotations to appear in wrong locations.

### MapKit vs GeoJSON

| System | Order | Example |
|---|---|---|
| MapKit (CLLocationCoordinate2D) | latitude, longitude | `CLLocationCoordinate2D(latitude: 37.77, longitude: -122.42)` |
| GeoJSON | longitude, latitude | `[-122.42, 37.77]` |
| Google Maps | latitude, longitude | Same as MapKit |
| PostGIS ST_MakePoint | longitude, latitude | Same as GeoJSON |

**The #1 coordinate bug**: Swapping lat/lng when parsing GeoJSON.

```swift
// ❌ WRONG: Using GeoJSON order directly
let coord = CLLocationCoordinate2D(
    latitude: geoJson[0],    // This is longitude!
    longitude: geoJson[1]    // This is latitude!
)

// ✅ RIGHT: GeoJSON is [lng, lat], MapKit wants (lat, lng)
let coord = CLLocationCoordinate2D(
    latitude: geoJson[1],
    longitude: geoJson[0]
)
```

### MKMapPoint vs CLLocationCoordinate2D

- `CLLocationCoordinate2D` — geographic coordinates (lat/lng in degrees)
- `MKMapPoint` — projected coordinates for flat map rendering
- Convert: `MKMapPoint(coordinate)` and `coordinate` property on MKMapPoint
- Never use MKMapPoint x/y as lat/lng — they're completely different number spaces

### Validation

```swift
func isValidCoordinate(_ coord: CLLocationCoordinate2D) -> Bool {
    coord.latitude >= -90 && coord.latitude <= 90
        && coord.longitude >= -180 && coord.longitude <= 180
        && !coord.latitude.isNaN && !coord.longitude.isNaN
}
```

If latitude > 90 or longitude > 180, coordinates are likely swapped or in wrong format.

---

## Console Debugging

### MapKit Logs

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

# Filter for your app
log stream --predicate 'process == "YourApp" AND (subsystem == "com.apple.MapKit" OR subsystem == "com.apple.CoreLocation")'
```

### Common Console Messages

| Message | Meaning |
|---|---|
| `No renderer for overlay` | Missing rendererFor delegate method |
| `Reuse identifier not registered` | Call register before dequeue |
| `CLLocationManager authorizationStatus is denied` | User denied location |

---

## Resources

**WWDC**: 2023-10043, 2024-10094

**Docs**: /mapkit, /mapkit/mklocalsearch

**Skills**: axiom-mapkit, axiom-mapkit-ref, axiom-core-location-diag