[Bug]: 'rnmapbox_maps/rnmapbox_maps-Swift.h' file not found — RNMBX_USE_FRAMEWORKS mismatch under Expo SDK 57 with static linkage

[backpackerhero]

Mapbox Version

default (MapboxCoreMaps 11.20.3 / MapboxMaps 11.20.3, as resolved by rnmapbox-maps 10.3.1)

React Native Version

0.86.0

Platform

iOS

@rnmapbox/maps version

10.3.1 (also confirmed on 10.3.2-rc.1, which only contains an unrelated Android fix)

Standalone component to reproduce

import Mapbox from '@rnmapbox/maps';
import { StyleSheet } from 'react-native';

const BugReport = () => {
return (
<Mapbox.MapView style={styles.map}>
<Mapbox.Camera centerCoordinate={[15.97, 45.81]} zoomLevel={14} />
</Mapbox.MapView>
);
};

const styles = StyleSheet.create({
map: { flex: 1 },
});

export default BugReport;

Observed behavior and steps to reproduce

Building fails during compilation of the rnmapbox-maps pod target with:

'rnmapbox_maps/rnmapbox_maps-Swift.h' file not found

#if RNMBX_USE_FRAMEWORKS
#import <rnmapbox_maps/rnmapbox_maps-Swift.h>
#else
#import <rnmapbox_maps-Swift.h>
#endif

(from node_modules/@rnmapbox/maps/ios/RNMBX/rnmapbox_maps-Swift.pre.h)

Environment:

• Expo SDK 57.0.2
• React Native 0.86.0
• New Architecture: enabled
• Xcode 26 (building via EAS Build, iPhoneSimulator26.4.sdk)
• CocoaPods 1.16.2
• iOS build configured with useFrameworks: static (via expo-build-properties), required because the project also uses @react-native-firebase (auth + app), which requires static linkage

During pod install, Expo's build pipeline logs:

[Expo] Disabling USE_FRAMEWORKS for 89 pods (... rnmapbox-maps ...)

This explicitly disables framework-style compilation for the rnmapbox-maps target, building it as a plain static library rather than a .framework. However, RNMBX_USE_FRAMEWORKS still evaluates truthy at compile time, so the code takes the framework-style import path, which only exists when the pod is actually compiled as a framework. Since it isn't under this configuration, the header can't be found.

Separately, and possibly related: this project also hit a CocoaPods TargetValidator error (verify_no_static_framework_transitive_dependencies) triggered by rnmapbox-maps's own Podfile hook forcing its underlying MapboxCommon / MapboxCoreMaps / MapboxMaps / Turf pods to dynamic frameworks, while the rest of the project (including rnmapbox-maps itself, and Firebase) is static. I worked around that specific error with a custom Podfile patch, which allowed pod install to succeed — but the Swift header issue above then surfaces during the actual Xcode compile step.

Expected behavior

rnmapbox-maps should compile successfully when the consuming project requires useFrameworks: static (e.g. due to a Firebase dependency) alongside RN 0.86 / Expo SDK 57's New Architecture build pipeline, which explicitly disables framework-style compilation for this pod. The Swift header import should resolve to the non-framework path (<rnmapbox_maps-Swift.h>) in that case, matching how the pod is actually being compiled.

Notes / preliminary analysis

I attempted to force RNMBX_USE_FRAMEWORKS=0 via GCC_PREPROCESSOR_DEFINITIONS on the rnmapbox-maps target in a Podfile post_install hook (both immediately after post_install's opening line, and again at the very end of the block to rule out an ordering/overwrite issue). Neither had any effect on the compile-time macro value. This suggests the macro may be controlled by a mechanism other than GCC_PREPROCESSOR_DEFINITIONS — possibly set directly in the pod's own generated xcconfig, or via a build step that regenerates rnmapbox_maps-Swift.pre.h or a related file at a point after post_install runs.

I also tried forcing DEFINES_MODULE=YES on the target directly — no effect on this specific error.

Question for maintainers: is there a documented/supported way to force non-framework Swift header resolution for rnmapbox-maps when a consuming project requires static linkage project-wide? Or is static linkage + New Architecture + Expo SDK 57 currently an unsupported combination for this library?

Additional links and references

Related closed issue (different symptom, same Xcode 26 / New Architecture territory): #4178

[github-actions]

No code example found in issue body - More info

[ashuvssut]

I hit this exact issue yesterday after upgrading to Expo SDK 57, and used Claude to find the root cause. Posting the full RCA since it explains both the pod install failure and why it only started with SDK 57 — hopefully useful for the maintainers and anyone else landing here.

• Note that I DONT UNDERSTAND ANY OF THESE iOS RCA written here. This RCA and the working TEMPORARY solution was completely provided by Claude

Environment: Expo SDK 57.0.2 (expo-modules-autolinking 57.0.4) · RN 0.86.0 · @rnmapbox/maps 10.3.1 (Mapbox 11.20.3) · CocoaPods 1.16.2 · New Architecture · useFrameworks: 'static' (required for react-native-firebase, together with forceStaticLinking)

❯ xcodebuild -version            
Xcode 26.6

Symptom

[!] The 'Pods-<App>' target has transitive dependencies that include statically linked binaries: (MapboxCoreMaps, MapboxCommon, and Turf)

Root cause: two Podfile hooks fighting over build types

Expo SDK 56+ enables the precompiled iOS pipeline by default (prebuilt React core via RCT_USE_PREBUILT_RNCORE=1 + EXPO_USE_PRECOMPILED_MODULES=1). Two pre-install hooks now run during pod install, and they disagree:

1. rnmapbox's hook ($RNMapboxMaps.pre_install in rnmapbox-maps.podspec) flips MapboxMaps, MapboxCoreMaps, MapboxCommon, and Turf to dynamic frameworks (rnMapboxMapsTargetsToChangeToDynamic).

2. Expo's hook (perform_pre_install in expo-modules-autolinking/scripts/ios/precompiled_modules.rb) then downgrades ~98 pods back to static libraries — the prebuilt React core doesn't support use_frameworks!, so Expo downgrades every pod that either (a) vendors an xcframework or (b) depends on React-Core:

   * [RNMapbox] Changed MapboxCommon to dynamic framework
   * [RNMapbox] Changed MapboxCoreMaps to dynamic framework
   * [RNMapbox] Changed MapboxMaps to dynamic framework
   * [RNMapbox] Changed Turf to dynamic framework
   [Expo] Disabling USE_FRAMEWORKS for 98 pods (…, MapboxCommon, MapboxCoreMaps, …, Turf, …, rnmapbox-maps)
   

   Note what's missing from Expo's downgrade list: MapboxMaps. It's a source-built Swift pod that neither vendors an xcframework nor depends on React-Core, so it slips through both of Expo's criteria and stays dynamic (rnmapbox's flip wins for that one pod only).

The result: a dynamic MapboxMaps pod whose dependencies (MapboxCoreMaps, MapboxCommon, Turf) are now static. That trips the second check in CocoaPods' TargetValidator#verify_no_static_framework_transitive_dependencies:

static_deps = dynamic_pod_targets.flat_map(&:recursive_dependent_targets).uniq.select(&:build_as_static?)
unless static_deps.empty?
  raise Informative, "The '#{aggregate_target.label}' target has transitive dependencies that include statically linked binaries: (#{static_deps.flat_map(&:name).to_sentence})"
end

(The bare pod names in the error — no file paths — confirm it's this check, not the vendored-static-artifacts one. The Mapbox 11.20.3 xcframework binaries themselves are all dynamic; nothing is actually statically linked, the build types just end up inconsistent.)

And as noted in the issue body, even if you patch pod install past this (e.g. by forcing MapboxMaps static too), compilation of rnmapbox-maps then fails on the RNMBX_USE_FRAMEWORKS header-path mismatch, because Expo builds the pod as a plain static library while the macro still takes the framework import path. So SDK 57's precompiled pipeline + useFrameworks: static + @rnmapbox/maps is currently a dead end at two separate stages.

Temporary workaround (I have verified that this solution is working)

Opt iOS out of the precompiled pipeline entirely via expo-build-properties — this is also the Expo maintainer's documented unblock for cases forceStaticLinking can't cover (expo/expo#39607 (comment)):

[
  "expo-build-properties",
  {
    "ios": {
      "buildReactNativeFromSource": true,
      "usePrecompiledModules": false,
      "useFrameworks": "static"
    }
  }
]

Then npx expo prebuild --clean -p ios. With the precompiled pipeline off, Expo's downgrade hook never runs, use_frameworks! :static applies consistently, rnmapbox's dynamic flip works exactly like it did on SDK ≤55, and both pod install and a full Xcode build succeed (verified with RNFB Analytics/Crashlytics/Perf in the same project).

Trade-off: The build takes very very long to finish. React Native and all Expo modules build from source again, so iOS build times very long. Android/web unaffected.

Note for maintainers

A proper fix probably needs $RNMapboxMaps.pre_install to detect Expo's precompiled pipeline (EXPO_USE_PRECOMPILED_MODULES=1 + RCT_USE_PREBUILT_RNCORE=1) and skip the dynamic flip so all Mapbox pods stay consistently static — plus making the RNMBX_USE_FRAMEWORKS macro follow the pod's actual build type rather than the USE_FRAMEWORKS env/property, since Expo now overrides build types per-pod after the podspec is evaluated.

[ashuvssut]

@backpackerhero The github-actions bot closed this issue because there is a missing Code example section. Can you check that github-actions bot comment and make necessary changes so that this issue reopens again

[mfazekas]

Fixed in v10.3.2-rc.2 can you test?!

[ashuvssut]

@mfazekas thankyou! its working fine for me now.

[backpackerhero]

Yes thank you its working!

Fixed in v10.3.2-rc.2 can you test?!