Why does a React Native iOS app crash when it first opens the camera if Info.plist lacks NSCameraUsageDescription, and how do you fix it?
answer
- iOS demands a purpose string first
- missing key: the system terminates the app
- one NS*UsageDescription key per resource
- set in Info.plist or ios.infoPlist
- native change: new binary, not OTA
basics
~20 siOS requires a purpose string for each protected resource before it shows a prompt; without NSCameraUsageDescription it terminates the app on camera access. Add a specific description to Info.plist, or ios.infoPlist in Expo, and ship a new binary.
solid answer
~40 sOn iOS, the permission prompt shows text the app supplies in `Info.plist`, one **usage-description key** per resource: `NSCameraUsageDescription` for the camera, `NSPhotoLibraryUsageDescription` to read the photo library, `NSPhotoLibraryAddUsageDescription` to only save to it, `NSMicrophoneUsageDescription`, `NSFaceIDUsageDescription` and so on. If code touches a protected resource and the key is missing, iOS does not prompt — it terminates the app. React Native core has no iOS permission API, so the access comes from the native camera or photo library module, and the fix is native configuration: add the key to `ios/<App>/Info.plist` in a bare app, or to `ios.infoPlist` (or a library's config-plugin option) in an Expo app. Write a specific reason, because the store reviews it, and remember that `Info.plist` changes need a new binary; an OTA update cannot add them.
code
json · 11 lines{
"expo": {
"ios": {
"infoPlist": {
"NSCameraUsageDescription": "The scanner uses the camera to photograph receipts and contracts you want to scan.",
"NSPhotoLibraryUsageDescription": "Choose existing photos of documents to turn them into scans.",
"NSPhotoLibraryAddUsageDescription": "Save finished scans to your photo library."
}
}
}
}go deeper
Recall that every protected iOS resource needs an NS*UsageDescription string in Info.plist, and that a missing one terminates the app on first access.
Explain where the key lives in bare and Expo projects, why only a new binary can add it, and how read and add-only photo keys differ.
Build it into release hygiene: audit each native library's required keys, tailor purpose strings, and test first-run access on a clean install before submission.
Own the privacy surface across apps: which resources the product may request at all, and who approves new purpose strings before they reach users and review.
## How iOS permission prompts work On iOS, access to the camera, microphone, photo library, location, contacts, Face ID and similar resources is gated by a **system prompt**. The prompt's body text is not written by the OS: it comes from a **purpose string** the app declares in its `Info.plist` under a resource-specific key. iOS treats that string as a precondition. If the app's code reaches a protected resource and the matching key is absent, the system does not fall back to a generic prompt; it **terminates the app**, which looks like a crash on first use. In a React Native app the access never comes from JavaScript directly. React Native core has no iOS permission API — `PermissionsAndroid` is Android-only — so the prompt is triggered by a native module: a camera library's request function, a photo-library module, a biometric module or a permissions library. All of them depend on the same `Info.plist` keys. ## The keys a document-scanning app needs | Resource | Key | Needed when | |---|---|---| | Camera | `NSCameraUsageDescription` | capturing pages with the camera | | Photo library, read | `NSPhotoLibraryUsageDescription` | reading the user's library through a library module | | Photo library, add only | `NSPhotoLibraryAddUsageDescription` | saving a scan into Photos without reading it | | Microphone | `NSMicrophoneUsageDescription` | recording video with audio | | Face ID | `NSFaceIDUsageDescription` | unlocking saved scans with Face ID | Face ID behaves slightly differently in one common module: `expo-local-authentication` checks for `NSFaceIDUsageDescription` itself and, when it is missing, authenticates with the device passcode instead, or resolves with the error `missing_usage_description` when device fallback is disabled, because calling Face ID would crash. ## Fixing it in each project type 1. **Bare React Native** — add the key and a string to `ios/<App>/Info.plist`, most easily in Xcode, then rebuild. 2. **Expo** — set it under `ios.infoPlist` in the app config, or use the option the library's config plugin exposes; prebuild then writes it into the generated `Info.plist`. 3. **Either way** — a new native build is required. The Expo docs state that `Info.plist` changes cannot be delivered over the air. ## Writing a purpose string that passes review The Expo permissions guide notes that libraries' config plugins insert boilerplate strings such as "Allow $(PRODUCT_NAME) to use Face ID", and that these usually need tailoring for the App Store to accept the app. A good string: - names the **feature**: "to photograph receipts and contracts you want to scan"; - matches what the app actually does with the data; - stays short, because it sits inside a system alert; - is localized along with the rest of the app. ## Android is the opposite shape | | iOS | Android | |---|---|---| | Declaration | purpose string in `Info.plist` | `<uses-permission>` in `AndroidManifest.xml` | | Missing declaration | app terminated on access | request refused without a prompt | | Explanation text | the purpose string, inside the system prompt | your own UI, or the `PermissionsAndroid` rationale | | After refusal | prompt never shown again | prompt usually shown again until a permanent refusal | ## Diagnosing the crash The failure is easy to misread as a bug in the camera library, because it happens exactly when the library first touches the camera. Two clues point at the purpose string instead: - the device log at the moment of termination names the missing usage-description key; - the crash reproduces only on first access, on every device, and disappears once the key is added — no code change needed. A related trap is a **dependency you did not expect**. A native library can reference a protected API — the photo library, location, the microphone — even if your app never calls that part. App Store processing can flag a build whose binary references such an API without the matching key, so audit what each native dependency links, not only what your code calls. ## Checklist before release - Every native library you added: which `Info.plist` keys does it need? - Is each purpose string specific to your feature, not the library's default? - Does a first-run test on a clean simulator hit every protected resource without a crash?
- A React Native team adds a scanning library and ships the JavaScript through an OTA update; iOS users crash on the Scan button. Why?Two native changes were skipped: the library's native code and its `Info.plist` purpose string only arrive in a new binary. An OTA update replaces JavaScript and assets, not native code or `Info.plist`, so the button calls into a module or a protected resource the installed build cannot serve. Ship a new build, and gate the feature on the native version.
- Why does saving a finished scan to Photos need a different key from importing one?iOS separates add-only access, `NSPhotoLibraryAddUsageDescription`, from read access, `NSPhotoLibraryUsageDescription`. An app that only saves should ask for the narrower one, which users grant more readily and which exposes none of their existing photos.
- PermissionsAndroid also shows the iOS camera prompt.
- Without the purpose string iOS shows a generic prompt instead.
- An OTA update can add a missing Info.plist key.
- The default config-plugin string is always good enough for review.
- Reading and saving photos use the same Info.plist key.