RCTAppDelegate.h File Not Found | Fix iOS Build Fast

You’re in Xcode, you hit Run, and the build stops: “RCTAppDelegate.h file not found.” One header, one red line, no app. It’s annoying because you didn’t write that header, and you can’t “just add it” like a missing file in a simple project.

This error almost always comes down to one of three things: the workspace isn’t wired to Pods, your AppDelegate files don’t match the React Native template your version expects, or Xcode is stuck using stale build settings. The fix is usually quick once you follow a clean order.

The steps below start with the fastest checks, then move into upgrade-specific changes. Do them in order. Make one change, rebuild once, then move on.

Why Xcode Throws This Error

Xcode shows “file not found” when the compiler can’t resolve an import during the build. It does not search your whole disk. It checks the header search paths and the module maps that your target and CocoaPods generate.

In React Native iOS projects, that header is surfaced through Pods. If the app target is not using the Pods configuration, the header won’t be visible even if it exists in the Pods folder. If your AppDelegate import line uses an older path style, the compiler may look in the wrong place. If your build caches are stale, Xcode can cling to old settings and keep failing.

• Opened The Wrong File — The .xcodeproj was opened instead of the .xcworkspace, so Pods headers never get linked in.
• Pods State Drifted — Pods installed, yet the generated xcconfig and header maps don’t match your current dependency set.
• Upgrade Missed Native Changes — Your React Native upgrade updated JS pieces, but your AppDelegate files stayed on an older template.
• Import Style No Longer Matches — The import points at a header path that does not exist in your current Pods layout.
• Build Cache Stuck — DerivedData and build artifacts keep Xcode pinned to old compile inputs.

If you recently bumped React Native, updated Xcode, switched Macs, changed Ruby/CocoaPods, or jumped between branches, you’re in the most common zone for this error.

RCTAppDelegate.h File Not Found Fix Steps

Start here. These steps solve a big chunk of cases without touching app code. After each step, run one build. Don’t stack changes.

1. Open The Workspace — Close Xcode, then open ios/YourApp.xcworkspace, not ios/YourApp.xcodeproj.
2. Clean The Build Folder — In Xcode, go to Product > Clean Build Folder, then build again.
3. Reset DerivedData — Quit Xcode, delete the DerivedData folder for this project, then reopen the workspace.
4. Reinstall Pods — Delete ios/Pods and ios/Podfile.lock, then run pod install from the ios folder.
5. Build Once From Terminal — Run your iOS build via CLI once to confirm you’re not dealing with an Xcode UI-only cache issue.

If that clears it, stop there. If you still see the error, move on to the AppDelegate checks next.

Pods Reinstall That Actually Resets Things

A normal pod install can succeed even when your project is stuck with stale settings. A clean reinstall forces CocoaPods to regenerate the project wiring and header maps.

1. Close Xcode First — Don’t leave the workspace open during cleanup.
2. Delete Pods And Lockfile — Remove ios/Pods and ios/Podfile.lock.
3. Run Pod Install — From ios, run pod install and wait for it to finish without errors.
4. Reopen The Workspace — Open the .xcworkspace and build again.

If your repo uses a lockfile policy, commit the new lockfile only when you understand why it changed. A surprise lockfile diff can hint at a Ruby/CocoaPods version mismatch.

RCTAppDelegate.h File Missing After a React Native Upgrade

This is the classic situation: JS dependencies install fine, Android runs, then iOS fails on a header that “used to work.” React Native upgrades can change native scaffolding, and Git merges don’t always catch it cleanly.

Two patterns show up often:

• Old AppDelegate Template — Your AppDelegate is still on an older style while your imports assume the newer base class.
• Wrong File Extension — Your AppDelegate is compiled as Objective-C when your current setup expects Objective-C++.

Check AppDelegate.h And The Import Line

Open ios/YourApp/AppDelegate.h and look for the import that references RCTAppDelegate. Many projects break because that import uses a path that no longer matches the current Pods export.

1. Find The Import — Look for a line that imports RCTAppDelegate.
2. Match The Expected Style — If your template expects a quoted import, use the quoted form. If it expects a module import, use that form. Keep it consistent with your installed React Native version and Pod layout.
3. Rebuild — Build once after changing the import so you can tell if that line was the blocker.

Keep your edits minimal. One line at a time beats a long “refactor” that hides the real cause.

Rename AppDelegate.m To AppDelegate.mm When Your Setup Needs It

Many recent React Native templates use an .mm AppDelegate in common setups, since native code paths can pull in C++ pieces. If your AppDelegate is still .m, the compiler mode can mismatch and trigger a cascade of missing headers and module build errors.

1. Rename The File On Disk — Change AppDelegate.m to AppDelegate.mm.
2. Fix The Xcode Reference — In Xcode, confirm the file path updates and the target still includes the file.
3. Clean And Build — Clean build folder, then run one build.

If your project already uses AppDelegate.mm, skip this. Don’t rename files “just in case.”

Taking The RCTAppDelegate.h File Not Found Error From Random To Repeatable

When this error keeps coming back, it usually means your project has a fragile native reset flow. You want a repeatable checklist that works after upgrades, branch swaps, and Xcode changes.

Use this mindset: confirm wiring first, then confirm Pods state, then confirm AppDelegate template, then chase edge cases. That order saves time because it hits the high-probability failures early.

1. Confirm .xcworkspace — If someone opens the .xcodeproj, the build can fail right away with missing headers.
2. Confirm Pods Config Is Active — Your target must use the Pods-generated base configuration files.
3. Confirm AppDelegate Matches Your RN Version — Compare to the upgrade helper diff for your exact version jump.
4. Confirm Cache Reset Was Real — Clearing DerivedData only helps if Xcode is fully closed and you rebuild once clean.

Once you treat this as a wiring problem instead of a “missing file,” the fixes stop feeling like guesswork.

Pods And Build Settings Checks That Matter

If the fast steps didn’t clear the error, verify that your app target is truly using the Pods settings. This is where the “file exists yet not found” cases live.

Base Configuration Must Point To Pods xcconfig

In Xcode, click your project, select your app target, open Build Settings, and search for “Base Configuration.” You should see Debug and Release pointing to Pods-generated xcconfig files. If they’re blank, CocoaPods wiring may be missing.

• Check Debug Config — It should reference a Pods-YourApp debug xcconfig file.
• Check Release Config — It should reference a Pods-YourApp release xcconfig file.

If those are missing, a Pod install can’t fully help until the project is wired back to those configs. In many cases, re-running CocoaPods integration from a clean state fixes it.

Confirm The Pod That Exposes The Header Is Present

Open ios/Podfile.lock and search for the pod that ships the AppDelegate header in your RN version. If the lockfile does not list it, the header won’t be available to your build.

1. Check Podfile Changes — Compare your Podfile to the template for your RN version.
2. Run Pod Install — Reinstall Pods after any Podfile edit.
3. Reopen Workspace — Build only from the .xcworkspace after Pods changes.

Quick Diagnosis Table

Symptom	Most Likely Cause	First Move
Pods folder has the header, build still fails	Target not using Pods configs	Check Base Configuration paths
Error started right after RN upgrade	AppDelegate template mismatch	Align AppDelegate files to template
Many module build errors at once	Wrong file extension or cache drift	Use .mm when needed, clean build
Works on device, fails on Simulator	Stale build artifacts for Simulator	Clear DerivedData, reinstall Pods

Pick the row that matches what you see, do the “First Move,” then rebuild. If it changes the error message, you’re moving in the right direction.

Xcode And Apple Silicon Gotchas

On Apple Silicon Macs, you can run into cases where a clean install still fails on the Simulator, then works on a physical device. That points to build artifacts and simulator slices, not your app logic.

Full Clean Order That Clears Stuck Artifacts

1. Quit Xcode — Don’t leave build processes running.
2. Delete DerivedData — Remove the project’s DerivedData folder.
3. Delete Pods And Lockfile — Remove ios/Pods and ios/Podfile.lock.
4. Install Pods Again — Run pod install in the ios folder.
5. Rebuild From Workspace — Open the .xcworkspace and build once clean.

Switch Simulator Target Once

If you upgraded Xcode, switching the simulator device can force a fresh compile in the current SDK. Pick another device model, clean build folder, then run again.

• Select A Different Device — Change the Run destination to another simulator model.
• Clean And Run — Clean build folder, then build again.

Command Line Tools Must Match Xcode

If terminal builds behave differently than Xcode builds, your system may be using a different Xcode toolchain in the terminal. Set your Command Line Tools to the Xcode version you’re using, then rebuild once clean.

1. Set Command Line Tools — Pick your current Xcode in Xcode settings.
2. Rebuild Clean — Clean build folder, then build again.

Clean Rebuild Checklist For Next Time

Once you’re building again, lock in a repeatable reset flow. It saves time the next time you bump dependencies or pull a branch with native changes. It also keeps your repo from collecting “mystery fixes” that nobody can explain later.

1. Install JS Packages First — Keep your JS deps in sync before touching Pods.
2. Run Pod Install From ios — Always run CocoaPods from the ios folder.
3. Open Only The Workspace — Treat the .xcodeproj as read-only.
4. Change One Thing Then Build — One edit, one build, repeat.
5. Align AppDelegate After RN Bumps — After a React Native bump, compare AppDelegate files to the template for that RN version.

If you hit the rctappdelegate.h file not found error again, start with the workspace check and Pods reset, then move to the AppDelegate import and file extension. That order catches the usual causes fast and keeps the fix clean.

If you still see “RCTAppDelegate.h File Not Found” after all steps, treat it as a wiring mismatch between your RN version, Podfile, and AppDelegate template. Re-check those three together, rebuild once, and you’ll almost always get the build back.