DYLD "Symbol not found: GestureType.singleTap" at launch — vendored MapboxNavigationCore xcframework vs CocoaPods-distributed MapboxMaps ABI mismatch?

[jacquesngomeheffa]

Summary

App crashes at launch (before any app code executes — dyld-level failure)
with a missing Swift symbol from MapboxMaps, despite the exact
Navigation↔Maps version pairing documented as required in this SDK's own
release notes being correctly resolved by CocoaPods.

Crash (raw .ips excerpt)

{
  "code": 4,
  "flags": 518,
  "namespace": "DYLD",
  "indicator": "Symbol missing",
  "details": ["(terminated at launch; ignore backtrace)"],
  "reasons": [
    "Symbol not found: _$s10MapboxMaps11GestureTypeO9singleTapyA2CmFWC",
    "Referenced from: <6639BD74-BED2-3BD2-8D0C-25DE8A4F3A1B> /Volumes/VOLUME/*/Navio.app/Frameworks/MapboxNavigationCore.framework/MapboxNavigationCore",
    "Expected in:     <0149B9A2-22C8-3E74-8C84-AE6C804CC83B> /Volumes/VOLUME/*/Navio.app/Frameworks/MapboxMaps.framework/MapboxMaps"
  ]
}

GestureType.singleTap exists in MapboxMaps' current public API — this
isn't a case that was removed. The symbol itself
(_$s10MapboxMaps11GestureTypeO9singleTapyA2CmFWC) is a Swift protocol
conformance witness table entry, consistent with a library-evolution ABI
mismatch between two different builds of "the same" MapboxMaps version,
rather than an actual API-level incompatibility. Note the two distinct
binary UUIDs above (6639BD74-... for MapboxNavigationCore,
0149B9A2-... for MapboxMaps) — happy to provide the full .ips if a
specific UUID lookup on Mapbox's side would help confirm which exact
build each one corresponds to.

Setup

• MapboxNavigationCore / MapboxNavigationUIKit / MapboxDirections /
  _MapboxNavigationHelpers: v3.11.0, vendored as precompiled xcframeworks
  downloaded from mapbox-navigation-ios-build-artifacts (official
  distribution channel).
• MapboxMaps / MapboxCommon / MapboxCoreMaps / Turf: installed via
  CocoaPods, through @rnmapbox/maps (RNMapboxMapsVersion: "11.14.0").
• This 11.14.0 pairing is exactly what v3.11.0's own release notes state
  is required ("Packaging: MapboxNavigationCore now requires MapboxMaps
  v11.14.0").
• Confirmed via a real pod install log that CocoaPods resolves
  MapboxMaps (11.14.0) correctly — this isn't a version-resolution
  problem.
• Confirmed via a second crash report on a genuinely fresh build (app
  fully uninstalled/reinstalled beforehand) — not a stale-binary artifact,
  and the identical symbol reappeared.
• React Native 0.79.6, Expo SDK 53, New Architecture (Fabric) enabled,
  useFrameworks: static, @rnmapbox/maps 10.1.44.

Question

Is mapbox-navigation-ios-build-artifacts's precompiled build of
MapboxNavigationCore guaranteed to be ABI-identical to the MapboxMaps
binary distributed via CocoaPods at the same version number? Or are these
two distribution channels (official precompiled artifacts vs. CocoaPods)
built through different pipelines that could produce non-ABI-identical
binaries for "the same" released version?

This seems related to the guidance given by @kried on #4703 regarding
vendoring MapboxNavigationCore alongside a separately-sourced MapboxMaps —
any clarification on whether that guidance still applies as of v3.11.0,
and specifically whether it explains this exact symbol-missing crash,
would help a lot.

What's already been ruled out

• Wrong version pairing (confirmed exact match to release notes)
• CocoaPods resolving the wrong MapboxMaps version (confirmed via pod
  install log)
• Stale/cached build (confirmed via a second crash on a fresh install,
  identical symbol)
• GestureType.singleTap being removed from the API (confirmed still
  present)

Happy to provide the full .ips crash report, Podfile.lock, or any other
diagnostic information needed.

[kried]

Hi @jacquesngomeheffa

Please note that if you use MapboxNavigationCore as an XCFramework, you should also provide all of its dependencies, including MapboxMaps, as xcframeworks. MapboxMaps is distributed through CocoaPods as source files, so this setup will not work in your app.

If you're using the mapbox-navigation-ios-build-artifacts package, please use the entire package, including MapboxMaps as an xcframework.