axiom-mapkit-diag

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