MapKit troubleshooting — annotations not appearing, region jumping, clustering not working, search failures, overlay rendering issues, user location problems
Diagnoses MapKit issues like missing annotations, region jumping, clustering failures, and search problems using structured decision trees.
npx claudepluginhub charleswiltgen/axiomThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Symptom-based MapKit troubleshooting. Start with the symptom you're seeing, follow the diagnostic path.
axiom-mapkit — Patterns, decision trees, anti-patternsaxiom-mapkit-ref — API reference, code examples| 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 |
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
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
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
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
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
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
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
Common coordinate mistakes that cause annotations to appear in wrong locations.
| 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.
// ❌ 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]
)
CLLocationCoordinate2D — geographic coordinates (lat/lng in degrees)MKMapPoint — projected coordinates for flat map renderingMKMapPoint(coordinate) and coordinate property on MKMapPointfunc 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.
# 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")'
| 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 |
WWDC: 2023-10043, 2024-10094
Docs: /mapkit, /mapkit/mklocalsearch
Skills: axiom-mapkit, axiom-mapkit-ref, axiom-core-location-diag
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.