Flutter/Flutter.h File Not Found | iOS Fixes That Work

Guide / By

Flutter/Flutter.h file not found means Xcode can’t see Flutter’s iOS headers; a clean rebuild plus a fresh CocoaPods install fixes it in most projects.

You’ll most often see this error when building iOS in Xcode, running flutter run, or archiving for TestFlight. The build log points at a file like GeneratedPluginRegistrant.h, then stops with a red “file not found” on . It feels scary, but it’s rarely “a missing file” in the normal sense.

Think of it like this: the header belongs to the Flutter iOS module that CocoaPods wires into your Xcode workspace. If that wiring is missing, stale, or pulled from the wrong place, Xcode can’t import Flutter’s module even when the header exists somewhere on disk.

Flutter/Flutter.h File Not Found

Xcode shows this error when an Objective-C or Swift file imports Flutter’s module and the build system can’t resolve it. In a standard Flutter app, the import usually happens through plugin registration, because plugins generate iOS code that references Flutter’s headers.

The fastest way to diagnose it is to spot where the import happens:

  • Check the failing file — If the log points to GeneratedPluginRegistrant.h, it’s commonly a pods/workspace linkage issue.
  • Check the target — If the log points inside a specific plugin’s iOS folder, it can be a plugin pod configuration or minimum iOS version mismatch.
  • Check how you opened Xcode — If you opened Runner.xcodeproj instead of Runner.xcworkspace, CocoaPods isn’t linked, and the import often fails right away.

If your repo builds on another Mac but not yours, that’s another clue. The Flutter code is fine; your local iOS build setup is drifting.

Fixing Flutter/Flutter.h Missing During iOS Build

This is the “do it first” path. It resets the most common breakpoints: stale pods, a mismatched lockfile, and cached build output. Run these steps in order.

  1. Quit Xcode — Close Xcode fully so it releases file locks and stops indexing cached paths.
  2. Clean Flutter builds — From the project root, run flutter clean.
  3. Refresh packages — Run flutter pub get so plugin registrants regenerate cleanly.
  4. Remove pod artifacts — Delete ios/Pods and ios/Podfile.lock.
  5. Install pods fresh — In ios/, run pod install.
  6. Open the workspace — Open ios/Runner.xcworkspace (not the .xcodeproj), then build.

If you only do one check, make it the workspace. CocoaPods integrates by generating and configuring the workspace. The project file can compile some sources, but pods won’t link correctly, and Flutter’s module import often fails.

Confirm CocoaPods Actually Linked Flutter

After pod install, open the workspace and look for a “Pods” project in the left sidebar. Then confirm you see Flutter-related pod targets inside Pods. If the Pods project is missing, CocoaPods did not integrate into the workspace.

If Pods exists but Flutter is missing, your Podfile may have drifted. A default Flutter app Podfile calls Flutter’s pod install helper. If you replaced large chunks of the Podfile, revert to Flutter’s default template and rerun the clean steps above.

Run One CLI Build To Get A Cleaner Log

Xcode’s UI logs can be noisy. One quick CLI build often shows the first real failure line:

  • Build without signing — Run flutter build ios --no-codesign once. If it fails with the same header import, you know it’s not a signing or scheme issue.
  • Spot the importer — Copy the exact file path that imports Flutter/Flutter.h. That importer tells you where to focus next.

When you see flutter/flutter.h file not found at this stage, the fix is still usually in the iOS integration layer, not your Dart code.

Fixing Add-To-App Setups And Mixed Xcode Workspaces

Add-to-app projects are more sensitive because there are two build systems in play: your host iOS app and the Flutter module. When the host app moves forward (Xcode settings, Swift version, deployment target) but the module’s generated iOS artifacts lag behind, imports can break in confusing ways.

Keep Generated iOS Artifacts Out Of Manual Edits

Flutter modules generate iOS folders that can be regenerated. If you hand-edit generated build files, they can be replaced later, or worse, they can lock you into a local state that nobody else can reproduce. Put custom iOS code in the host app or in a plugin, not inside generated module output.

Use One Flutter Source In Your Podfile

A classic add-to-app trap is pulling Flutter from two places at once (a local engine cache plus a module path). CocoaPods can warn about multiple Flutter sources. Even when it installs, Xcode can end up referencing the wrong pod target, then the header import fails later.

  • Pick one Flutter source — Keep only the Flutter module path or the intended Flutter pod source, not both.
  • Recreate pods — Delete Pods and Podfile.lock, then run pod install again.
  • Reopen the workspace — Close Xcode, then reopen the host app workspace so it reloads the regenerated pod graph.

Be Careful With use_frameworks! And Custom Hooks

Some host apps rely on use_frameworks! or a custom post_install hook for other native dependencies. Those edits can change how pods are built and imported, which can affect how Flutter headers are exposed.

  1. Revert to defaults temporarily — Remove use_frameworks! and comment out the post_install block, then reinstall pods and build once.
  2. Add changes back slowly — Restore one change at a time, reinstall pods, and build. This makes the exact trigger obvious.
  3. Avoid touching search paths blindly — If your hook edits header or framework search paths without a tight reason, it can erase settings that Flutter expects.

This is slow, but it beats guessing. Once you find the line that breaks it, you can fix just that part instead of living in rebuild loops.

Checking Xcode Settings That Commonly Break The Import

After a big Xcode upgrade, a plugin update, or manual tinkering, the workspace can build with settings that look fine in the UI but are wrong under the hood. These checks are quick and often spot the “one checkbox” issue.

Open The Workspace And Inspect The Runner Target

In Xcode, select the Runner project, then the Runner target, then look at Build Settings. You don’t need to rewrite settings by hand. You’re just checking for drift that blocks Flutter’s module from being found.

  • Validate the deployment target — If plugins require a higher iOS version than your target, compilation can fail mid-stream and surface header errors. Raise the target if needed, then reinstall pods.
  • Check the build configuration — Make sure you’re building the correct configuration (Debug vs Release) and the correct scheme. A stale scheme can point to a target that never links pods.
  • Reset derived data — If the workspace is correct but Xcode keeps “remembering” old paths, delete DerivedData for the project and build again.

Confirm Xcode Command Line Tools Match Your Installed Xcode

When command line tools point to an older Xcode, builds can use old SDK paths and fail in odd ways. A quick check:

  • Print the selected path — Run xcode-select -p and confirm it matches your active Xcode install.
  • Switch if needed — If it’s wrong, select the current Xcode in Xcode’s Preferences or via xcode-select, then rebuild.

If your machine recently changed (new Mac, new Xcode), this check alone can save you.

When CocoaPods Or Ruby Is The Root Cause

If the repo builds on another Mac, you’ve opened the workspace, and you’ve done a clean pod reinstall, your CocoaPods toolchain is a prime suspect. This doesn’t mean you need to become a Ruby expert. You just need a consistent pods install that matches your Xcode toolchain.

Try these steps in order, stopping when the build starts working:

  1. Check your CocoaPods version — Run pod --version and write it down so you can compare across machines.
  2. Update pod repos — Run pod repo update, then reinstall pods.
  3. Reinstall CocoaPods cleanly — If CocoaPods was installed a long time ago via Ruby gems, reinstalling via Homebrew often fixes path and permission issues that block correct framework linkage.
  4. Reinstall pods from scratch — Delete Pods and Podfile.lock again, then run pod install.

Apple Silicon machines add one more twist: running pods under Rosetta sometimes produces pods that don’t match your current architecture mode. If you’ve mixed Intel and ARM terminals, pick one mode for the project, then reinstall pods from a clean slate.

If you use Bundler, running bundle exec pod install can keep everyone on the same CocoaPods version. That reduces “works on my Mac” moments when teams share a repo.

Symptom Match Table For Faster Fixes

This table helps you pick the first move based on what you’re seeing. It’s not a magic list. It’s a way to avoid random clicking.

What You See Likely Cause First Fix To Try
Error points at GeneratedPluginRegistrant.h Pods not linked or workspace not used Open Runner.xcworkspace, reinstall pods
Pods project missing in Xcode CocoaPods didn’t integrate Run pod install in ios/, reopen workspace
Flutter pod missing under Pods Podfile drift or wrong Flutter source Restore Flutter Podfile snippet, reinstall pods
Fails only on one Mac Pod toolchain mismatch Reinstall CocoaPods, clear pods and rebuild
Fails after adding one plugin Plugin iOS requirements or pod graph change Upgrade plugin, raise iOS target, reinstall pods

Keeping The Fix Stable After Upgrades

Once you’ve cleared the build, you can keep it stable with a few simple habits. They reduce drift across machines and keep the iOS side predictable when Flutter, Xcode, or plugins change.

  • Commit your Podfile setup — Keep ios/Podfile in version control. It’s part of your build, not a local preference.
  • Keep Podfile.lock in app projects — For standard Flutter apps, committing Podfile.lock keeps pod resolution consistent across machines.
  • Avoid editing generated Flutter build files — Generated configs can be replaced. Put custom native changes in the right place (host app or plugin) so they persist cleanly.
  • Do one full reset after major upgrades — After a big Flutter upgrade or Xcode jump, run the clean + fresh pods flow once. It’s faster than chasing stray cache issues later.

If you hit the same error again, treat it as a signal that your iOS integration glue needs a reset. Don’t rewrite random build settings. Start with the workspace, then a clean rebuild, then a fresh pods install. When that doesn’t do it, isolate the trigger by changing one thing at a time.

When you see flutter/flutter.h file not found, the importer line in the build log is your north star. Track that file, then fix what feeds it: workspace linkage, pods, toolchain, or a single plugin change.

References: Flutter docs: Add to app · Flutter docs: iOS project setup