iOS build fails to link (Undefined symbols: SentryInternalSwizzleApi.Mode.oncePerClass) when consuming the default prebuilt Sentry.xcframework

[mikewesthad]

What React Native libraries do you use?

Expo Application Services (EAS), Expo (mobile only), Hermes

Are you using sentry.io or on-premise?

sentry.io (SaS)

Are you using any other error monitoring solution alongside Sentry?

Yes

Other Error Monitoring Solution Name

No response

@sentry/react-native SDK Version

8.19.0

How does your development environment look like?

@sentry/react-native: 8.19.0
sentry-cocoa (pinned by RNSentry RNSentry.podspec): 9.19.1
react-native: 0.83.6
expo: 55.0.27
Build: EAS Build, iOS sdk-55 image, device (arm64) release build
SENTRY_USE_XCFRAMEWORK: unset (i.e. the new default prebuilt-xcframework path)

Sentry.init()

Sentry.init({
  dsn: "https://XXX@oXXXX.ingest.us.sentry.io/XXXX",
  release: getSentryReleaseIdentifier(),
  profilesSampleRate: 1.0,
  environment: getEnvironment(),
  attachScreenshot: false,
  attachViewHierarchy: false,
  attachThreads: true,
  attachAllThreads: true,
  dist: Updates.updateId ?? undefined,
});

Steps to Reproduce

1. Use @sentry/react-native 8.19.0 on iOS with the default integration (prebuilt Sentry.xcframework; SENTRY_USE_XCFRAMEWORK unset).
2. Build the iOS app for a real device (arm64). Ours is an Expo (CNG) app built on EAS Build (JS-1173 image).
3. The Xcode/ld link step fails (see Actual Result). Setting SENTRY_USE_XCFRAMEWORK=0 (source build) makes it succeed.

Expected Result

The app links against the prebuilt Sentry.xcframework and builds successfully, with no need to fall back to the source-built CocoaPod.

Actual Result

Link step fails:

Undefined symbols for architecture arm64
┌─ Symbol: enum case for Sentry.SentryInternalSwizzleApi.Mode.oncePerClass(Sentry.SentryInternalSwizzleApi.Mode.Type) -> Sentry.SentryInternalSwizzleApi.Mode
└─ Referenced from: function signature specialization <Arg[1] = Dead> of static RNSentry.RNSentryInternal.swizzleRNSScreenViewDidAppear(hook: () -> ()) -> () in RNSentry[28](RNSentryInternal.o)

ld: symbol(s) not found for architecture arm64
clang: error: linker command failed with exit code 1 (use -v to see invocation)

Likely cause is the interaction of two changes that landed for 8.18/8.19:

• refactor(ios): Migrate from PrivateSentrySDKOnly to SentrySDK.internal #6380, migrating iOS from PrivateSentrySDKOnly to SentrySDK.internal, which introduced the SentryInternalSwizzleApi reference in RNSentryInternal.swizzleRNSScreenViewDidAppear.
• feat(ios): Consume sentry-cocoa as a prebuilt xcframework by default #6413 / feat(ios): Default to consuming sentry-cocoa as an xcframework #6381, making the prebuilt Sentry.xcframework the default (Investigate how moving to precompiled xcframework could be done #6080).

SentryInternalSwizzleApi.Mode.oncePerClass is an internal/@_spi Swift symbol that the prebuilt static Sentry.xcframework slice doesn’t vend, so RNSentry (compiled separately) can’t resolve it at link time. Building sentry-cocoa from source (SENTRY_USE_XCFRAMEWORK=0) keeps both in the same module graph and links cleanly.

[linear-code]

RN-712