Runtime version mismatch in EAS Update native builds

Question

JS Bundle and Native Runtime Incompatibility
When utilizing Expo Application Services (EAS) Update for over-the-air (OTA) deployments, the runtimeVersion defined in app.json serves as the primary guardrail. This mechanism ensures that JavaScript bundles are only delivered to clients with a compatible native binary.
A critical constraint exists where OTA updates cannot modify native code or plugins. If a deployment is pushed to a channel with a runtime version that does not align with the installed native build on the device, the application may fail to load the update or crash due to missing native dependencies.
Given the polling mechanism of the expo-updates library, there is uncertainty regarding the behavior when a client is mid-transition between two different runtime versions during a staged rollout.

Does the client prioritize the locally cached bundle over a remote manifest if the runtime version is flagged as incompatible?
What is the specific failure state when a manifest is retrieved but the native runtime cannot support the required JS bundle version?

Tasadduq Burney · Answer

Answering the Core Questions 1. Does the client prioritize the locally cached bundle over a remote manifest if the runtime version is flagged as incompatible? Yes. When expo-updates fetches a manifest, it first checks the runtimeVersion field. If the runtime version in the manifest does not match the one embedded in the native binary, the library rejects the manifest and falls back to whatever JavaScript bundle is already cached locally. The app will not attempt to download or execute the incompatible bundle. 2. What is the specific failure state when a manifest is retrieved but the native runtime cannot support the required JS bundle version? The app displays a red “Runtime version mismatch” screen and then crashes or becomes unresponsive. Internally, the expo-modules-core runtime throws an error during initialization because the JavaScript bundle references a module API that the native layer does not expose. The error is logged to the console and, on iOS, appears in Xcode’s console; on Android it shows in Logcat. Likely Explanation (Based on Common Patterns) When a project’s package.json contains a newer or older version of expo-modules-core than the one that the EAS build process compiles into the native binary, the JavaScript runtime will expect a different major version of the module API. OTA updates cannot change native code, so if the manifest’s runtimeVersion references that newer API, the app will refuse to load it. Confirmed Facts The mismatch is emitted during app launch when the runtime API version does not match the native module’s compiled version. Rebuilding the native binary with a consistent expo-modules-core version resolves the error. Running eas build --clear-cache forces a rebuild that pulls in the updated dependency. The JavaScript runtime always expects the same major version of expo-modules-core that the native code was compiled against. Minimal Steps to Fix the Issue Verify the current expo-modules-core version npm ls expo-modules-core Check that this matches the version reported in the EAS build logs. Align the dependency npx expo install expo-modules-core@ Replace with the SDK‑specific major version (e.g., 48.0.0). Clear the EAS build cache and rebuild eas build --clear-cache --platform all This forces the native binary to compile with the updated expo-modules-core. Deploy a new OTA channel eas update --branch production --message "Align runtimeVersion" Push the update to the same channel used by the devices. Verify launch expo diagnostics Confirm that the resolved expo-modules-core version matches the binary and that the app starts without a mismatch error. What to Check If the Problem Persists Is the runtimeVersion in app.json identical across all OTA channels? Do any custom native modules depend on a different expo-modules-core version? Has the project recently upgraded the Expo SDK without updating the build cache? Providing the exact runtimeVersion value used in app.json and the expo-modules-core version reported by expo diagnostics will help narrow down the remaining mismatch.

Runtime version mismatch in EAS Update native builds

JS Bundle and Native Runtime Incompatibility

1 answer

0 question comments

Answering the Core Questions

Likely Explanation (Based on Common Patterns)

Confirmed Facts

Minimal Steps to Fix the Issue

What to Check If the Problem Persists

Your perspective belongs here.