An Expo app on the appVersion runtimeVersion policy adds a native camera module, the team publishes an EAS Update without bumping version, and 1.4.0 users crash at launch: what went wrong, and how do you prevent it?

## What the team shipped A typical timeline for this failure: 1. Version `1.4.0` of the app is built and released to the stores. Its app config has `"version": "1.4.0"` and `"runtimeVersion": { "policy": "appVersion" }`, so every 1.4.0 binary reports runtime version `1.4.0`. 2. A developer adds `expo-camera` for a new scanning screen. The library has a JavaScript half and a native half. 3. The screen is finished, and the team runs `eas update` from the main branch. Nobody changes `version`. 4. Over the following app launches, crash reports arrive from 1.4.0 users on both platforms, all at launch. ## Why EAS delivered the update With the `appVersion` policy, `eas update` resolved the runtime version from the unchanged `version` field: still `1.4.0`. EAS Update matches updates to builds by **exact** runtime version and platform, so every 1.4.0 build accepted the update. Nothing in the pipeline inspected which native modules the bundle imports; the runtime version is a label the project asserts, and here the label was wrong. ## Why it crashes at launch The JavaScript half of an Expo module looks up its native half when it is imported. `expo-camera` calls `requireNativeModule('ExpoCamera')`, and when the binary has no such module that call throws `Cannot find native module 'ExpoCamera'`. When the screen that imports it is loaded at startup, as it is when the import sits at module scope in a file the app evaluates on launch, the error fires before the first screen renders. `expo-updates` has error recovery that may mark a freshly launched update as failed and fall back to an older update when the error happens before the first view appears. Treat it as a last resort: users may still see a crash, and an error thrown after content has appeared is not rolled back. ## Stopping the damage and the real fix - **Stop the damage:** serve the last good bundle to runtime `1.4.0` again, by republishing the previous update or rolling back. Those commands have their own mechanics; the point here is that the fix is published to the same runtime version that is broken. - **Ship the feature properly:** bump `version` to `1.5.0`, make and submit new builds (runtime `1.5.0`), and publish the camera screen as an update for that runtime only. - **Keep 1.4.0 serviceable:** once main contains the camera code, any update built from main is wrong for 1.4.0. Hotfixes for 1.4.0 must come from a branch cut at the 1.4.0 release, which still resolves to runtime `1.4.0`. ## Diagnosing it with evidence | Evidence | What it tells you | |---|---| | `Updates.runtimeVersion` and `Updates.updateId` logged with the crash | Which native layer and which update were running | | The crash message `Cannot find native module '...'` | A JS-to-native mismatch, not a logic bug | | `eas fingerprint:compare --build-id <build> --update-id <update>` | The native inputs that differ between the store build and the update, such as a new autolinked package | ## Preventing a repeat 1. **Make the label follow native changes.** Either adopt a rule that any native change bumps `version`, or switch to `{ "policy": "fingerprint" }`, which changes the runtime version automatically. With fingerprint the same mistake produces an update that no installed build matches: nobody receives it, so no installed build runs it. 2. **Check before publishing.** In CI, run `npx expo-updates runtimeversion:resolve --platform ios` (and `android`) to print the runtime version the publish would target, and compare the project with the last store build using `eas fingerprint:compare`. 3. **Limit the blast radius.** Publish to a small percentage first and test on a preview build that shares the production runtime. 4. **Mind JS guards.** `requireOptionalNativeModule` from `expo` returns `null` instead of throwing, so it can hide a feature whose native half is missing, but only if nothing imports the library eagerly. It is a mitigation, not a substitute for a correct runtime version. ## Why the other policies would not have saved it - `nativeVersion` resolves from `version` and the build number. Publishing without a new build changes neither, so the update would have carried the old runtime just the same. - A hand-managed string fails the same way unless someone edits it. - Only `fingerprint` recomputes from the native inputs themselves, which is why it turns this crash into an update that nobody receives. ## The lesson Every policy other than `fingerprint` is a promise made by people. `appVersion` and `nativeVersion` are only as correct as the discipline of bumping numbers when native code changes; a manual string is only as correct as the person editing it.