Diagnosing AsyncStorage Persistence Failures and Migration Issues in React Native 0.73+

Problem: Data written with AsyncStorage disappears after a process kill or app restart

In React Native 0.73 and later, developers frequently encounter a situation where a value stored via AsyncStorage.setItem is not readable after the app is terminated and relaunched. The symptom is reproducible on both iOS and Android and typically points to two root causes: blocking the UI thread during the write, or skipping a schema‑version migration when the storage format changes.

Cause / Diagnostic Quick‑Reference

Observed behavior	Most likely cause	First check
Write succeeds but read returns null after restart	AsyncStorage call executed on the UI thread, causing the write to be dropped when the JS thread is paused	Verify that every setItem/getItem call uses the promise API and is scheduled off the UI thread
Data exists on first launch but disappears after a version bump	Missing migration logic for a new schema version key	Inspect the upgrade routine for a version key (e.g., storageSchemaVersion) and a migration function
Intermittent “dead object” warnings in the console	Out‑of‑date AsyncStorage native module (< 0.6) on iOS 16+	Confirm the installed @react-native-async-storage/async-storage version ≥ 1.21.0 (which bundles native 0.6+)

Ordered Diagnostic Checks

1. Confirm promise‑based usage. Search the codebase for AsyncStorage.setItem and AsyncStorage.getItem. Each call must be awaited or chained with .then(). Synchronous‑style wrappers (e.g., a custom setItemSync) are a red flag.
2. Check threading. Ensure writes are not performed directly inside render or event handlers that run on the UI thread. The recommended pattern is:

   import { InteractionManager } from 'react-native';
   import AsyncStorage from '@react-native-async-storage/async-storage';
   
   function persistUserToken(token) {
     InteractionManager.runAfterInteractions(() => {
       AsyncStorage.setItem('authToken', token).catch(console.error);
     });
   }

3. Validate migration script. Look for a key that stores the current schema version, e.g. storageSchemaVersion. A typical migration block runs once at app start:

   const CURRENT_VERSION = 2;
   
   async function migrateStorage() {
     const savedVersion = await AsyncStorage.getItem('storageSchemaVersion');
     const version = savedVersion ? parseInt(savedVersion, 10) : 0;
     if (version === CURRENT_VERSION) return;
   
     if (version === 0) {
       // v0 → v1: rename legacy keys
       const old = await AsyncStorage.getItem('userToken');
       if (old) await AsyncStorage.setItem('authToken', old);
     }
     if (version <= 1) {
       // v1 → v2: add new fields
       await AsyncStorage.setItem('preferences', JSON.stringify({ theme: 'system' }));
     }
     await AsyncStorage.setItem('storageSchemaVersion', String(CURRENT_VERSION));
   }

4. Verify native module version. Run npm ls @react-native-async-storage/async-storage (or yarn list) in the project root. The package should resolve to ≥ 1.21.0, which ships the native 0.6+ implementation required for iOS 16 encryption support.

Fixes Tied to Findings

1. Move all AsyncStorage calls off the UI thread

Wrap every write/read in InteractionManager.runAfterInteractions or dispatch to a dedicated background queue via setTimeout(() => …, 0) if you cannot use InteractionManager. This prevents the JS thread from being blocked long enough for the native bridge to drop the operation.

2. Implement a versioned migration routine

Adopt the pattern shown in Check 3. Store a single integer version key and apply incremental transformations. Run the migration early (e.g., in the root component’s useEffect before any other AsyncStorage access). Guard the migration with a try/catch and log the old/new version numbers for audit.

3. Upgrade the AsyncStorage package

If the installed version is older than 1.21.0, upgrade:

npm install @react-native-async-storage/async-storage@latest
# or
yarn add @react-native-async-storage/async-storage@latest

Then rebuild the native binaries (cd ios && pod install && cd .. && npx react-native run-ios / npx react-native run-android).

Verification Steps (run after each fix)

1. Launch the app, write a test key: await AsyncStorage.setItem('diagnosticTest', 'ok').
2. Terminate the process completely (swipe away from recent apps on Android; double‑tap home and swipe up on iOS).
3. Relaunch the app and read the key: const v = await AsyncStorage.getItem('diagnosticTest'). Confirm v === 'ok'.
4. If a migration ran, open the console and verify a log line such as Migration 0 → 2 completed appears exactly once.

Escalation Criteria

• Migration throws repeatedly (caught errors logged) after three retries.
• Data corruption persists on a fresh device/emulator with a clean install.
• Native module crashes (e.g., RCTFatalException on iOS) when calling setItem.

When any of the above occurs, capture the full stack trace, the AsyncStorage version, React Native version, and OS version, then file an issue in the @react-native-async-storage/async-storage repository or your internal ticketing system.

Limitations & Practical Checks

This guide covers the most common persistence failures in React Native 0.73+. It does not address:

• Encrypted storage alternatives (e.g., react-native-keychain) – those have separate migration concerns.
• Large‑blob performance; AsyncStorage is not suited for > 6 MB payloads.

A quick sanity check you can run on any device: add a temporary button that executes the verification steps above and displays the result in an alert. If the alert shows the expected value, the storage layer is functioning correctly for the current schema version.

Diagram Labels

• AsyncStorage write
• UI thread block
• Migration script
• Verification flow