While running `pod install` or building a React Native iOS project, you may encounter `[!] Unable to find a specification for RNWorklets depended upon by RNReanimated` or `'RNWorklets/StableAPI.h' file not found`. These errors usually appear after upgrading React Native, installing or updating React Native Reanimated, or moving from Reanimated 3.x to Reanimated 4.x. Although React Native code generation may complete successfully, CocoaPods can still fail because it cannot resolve the native Worklets dependency required by Reanimated 4.

The Error

1[!] Unable to find a specification for `RNWorklets` depended upon by `RNReanimated`
2
3You have either:
4 * mistyped the name or version.
5 * not added the source repo that hosts the Podspec to your Podfile.

You may also see a related Xcode build error after `pod install`. This usually means the `RNWorklets` pod was not installed correctly, the Worklets headers were not generated, or Xcode is still using stale build artifacts.

1fatal error: 'RNWorklets/StableAPI.h' file not found
2#import RNWorklets/StableAPI.h
3         ^~~~~~~~~~~~~~~~~~~~~~~
41 error generated.

What Causes This Error

Reanimated 4 depends on the separate `react-native-worklets` package. During iOS pod installation, CocoaPods tries to resolve the `RNWorklets` pod. If `react-native-worklets` is missing, incompatible, corrupted, or not linked correctly, pod installation can fail before the iOS project builds. If pod installation succeeds but headers are stale or missing, Xcode may fail later with `StableAPI.h file not found`.

• `react-native-worklets` package is missing
• Reanimated and Worklets versions are incompatible
• Worklets Babel plugin is missing from `babel.config.js`
• Old `react-native-reanimated/plugin` is still used with Reanimated 4
• Corrupted `node_modules` directory
• Stale Pods or Podfile.lock files
• Incomplete dependency installation
• Upgrading React Native without upgrading Reanimated dependencies
• Mixing Reanimated 3.x and 4.x setup instructions
• Stale Xcode DerivedData caching old header paths

Fix 1: Check Installed Versions

Before changing dependencies, verify which Reanimated version is installed and whether `react-native-worklets` exists in your project.

1npm ls react-native-reanimated
2npm ls react-native-worklets

Fix 2: Install React Native Worklets

If you are using Reanimated 4, install `react-native-worklets`. The Worklets version should be compatible with your installed Reanimated version.

1npm install react-native-worklets
2
3cd ios
4pod install

Fix 3: Add the Worklets Babel Plugin

For Reanimated 4, make sure your `babel.config.js` uses the Worklets Babel plugin. If your config still uses `react-native-reanimated/plugin`, replace it with `react-native-worklets/plugin`. Keep the plugin last in the plugins array.

1module.exports = {
2  presets: ['module:@react-native/babel-preset'],
3  plugins: [
4    'react-native-worklets/plugin'
5  ]
6};

Fix 4: Delete Pods and Reinstall

Outdated pod metadata can prevent CocoaPods from resolving `RNWorklets` correctly. Delete Pods and regenerate the iOS dependencies from scratch.

1cd ios
2
3rm -rf Pods
4rm -f Podfile.lock
5
6pod install --repo-update

Fix 5: Reinstall Node Modules

If JavaScript dependencies are corrupted or partially installed, removing `node_modules` and reinstalling packages can restore missing native references.

1rm -rf node_modules
2rm -f package-lock.json
3
4npm install
5
6cd ios
7rm -rf Pods
8rm -f Podfile.lock
9pod install --repo-update

Fix 6: Clear Xcode DerivedData

If `pod install` succeeds but Xcode still shows `StableAPI.h file not found`, stale build artifacts in DerivedData may be pointing to old header paths. Clearing DerivedData forces Xcode to rebuild the iOS project with fresh native headers.

1rm -rf ~/Library/Developer/Xcode/DerivedData
2
3cd ios
4pod install
5cd ..
6
7npm run ios

Fix 7: Verify Reanimated Compatibility

Different Reanimated versions have different setup requirements. Reanimated 4 requires `react-native-worklets`, while Reanimated 3 uses the older Reanimated setup. Avoid mixing Reanimated 3.x instructions with Reanimated 4.x dependencies.

1npm ls react-native-reanimated
2npm ls react-native-worklets

Fix 8: Update CocoaPods Repository

Older local CocoaPods metadata can sometimes prevent pods from resolving correctly. Updating the pod repository ensures CocoaPods uses the latest available podspec information.

1cd ios
2
3pod repo update
4pod install --repo-update

Fix 9: Reinstall React Native Reanimated

If Reanimated and Worklets versions are mismatched, reinstalling Reanimated and then reinstalling pods can resolve dependency conflicts.

1npm uninstall react-native-reanimated
2npm install react-native-reanimated
3
4cd ios
5pod install --repo-update

Fix 10: Reset Metro Cache

After changing Reanimated, Worklets, or Babel configuration, reset the Metro cache. This helps prevent JavaScript from being transformed with an old plugin configuration.

1npm start -- --reset-cache

Example Failure Log

1Analyzing dependencies
2
3Fetching podspec for `hermes-engine`
4
5[!] Unable to find a specification for `RNWorklets`
6depended upon by `RNReanimated`
7
8You have either:
9 * mistyped the name or version.
10 * not added the source repo that hosts the Podfile.

Quick Diagnosis Checklist

• Verify the installed Reanimated version
• Check whether `react-native-worklets` is installed
• Install a compatible `react-native-worklets` version
• Use `react-native-worklets/plugin` in `babel.config.js` for Reanimated 4
• Keep the Worklets Babel plugin last in the plugins array
• Delete Pods and Podfile.lock
• Run `pod install --repo-update`
• Remove and reinstall node_modules
• Clear Xcode DerivedData if `StableAPI.h` error persists after pod install
• Ensure Reanimated and Worklets versions are compatible
• Update CocoaPods repository
• Reset Metro cache after changing Babel config
• Rebuild the app after successful pod installation