'Flutter/Flutter.h' file not found in iOS

This comprehensive guide addresses the common but frustrating "Flutter/Flutter.h file not found" error when building Flutter applications for iOS. This error typically occurs when the iOS project structure becomes misconfigured or there are issues with CocoaPods integration.

Problem Overview

The error manifests as a compilation failure with messages like:

'Flutter/Flutter.h' file not found
#import <Flutter/Flutter.h>

This indicates that the iOS build system cannot locate the Flutter framework headers, which are essential for native iOS-Flutter communication. The error often affects multiple plugins simultaneously and typically occurs after:

• Switching between Flutter channels
• Updating Flutter or Xcode
• Adding/removing plugins
• Merging code changes that affect the iOS project structure
• Moving projects between different development environments

Primary Solutions

1. Flutter Cache and Dependency Repair

Start with these basic cleanup commands that resolve many common issues:

flutter clean
flutter pub get
flutter pub cache repair
cd ios
pod install --repo-update
cd ..
flutter run

TIP

flutter pub cache repair is particularly effective for fixing corrupted package caches that can cause header file issues.

2. Complete iOS Project Regeneration

If the basic cleanup doesn't work, regenerate your iOS project:

1. Back up your iOS folder contents (especially Runner.xcworkspace, Info.plist, assets, and configuration files)
2. Delete the entire ios folder from your project
3. Run this command from your project root:

   flutter create .

4. Restore your backed-up files to the new ios folder
5. Navigate to the ios directory and run:

   pod install

6. Return to the project root and run your app:

   flutter run

3. CocoaPods and Xcode Configuration

Podfile Verification

Ensure your Podfile contains the essential post-install hook:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
  end
end

Platform Version Configuration

Update the platform version in your Podfile to match modern iOS requirements:

# Uncomment this line to define a global platform for your project
platform :ios, '13.0'  # Or your minimum supported version

Build Script Order

In Xcode, verify that the Flutter build script is positioned correctly:

1. Open your project in Xcode (ios/Runner.xcworkspace)
2. Select the Runner target
3. Go to Build Phases
4. Ensure the "Run Script" phase containing /bin/sh "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" build appears before the "Compile Sources" phase

WARNING

Modifying build phase order manually can resolve issues caused by adding custom scripts (like Crashlytics) that might have been placed incorrectly.

4. Xcode Build Settings

Try these Xcode configuration changes:

1. In Xcode, go to Runner → Build Settings
2. Search for "Allow Non-modular Includes In Framework Modules"
3. Set this value to YES

Alternatively, you can add this configuration to your Podfile:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['CLANG_ALLOW_NON_MODULAR_INCLUDES_IN_FRAMEWORK_MODULES'] = 'YES'
    end
    flutter_additional_ios_build_settings(target)
  end
end

5. Channel Switching

If you're using the Flutter master channel, consider switching to the stable channel:

flutter channel stable
flutter clean
flutter run

INFO

The master channel contains cutting-edge changes that may occasionally break compatibility with plugins. The stable channel is recommended for production development.

Advanced Troubleshooting

Plugin-Specific Solutions

Some plugins (particularly permission_handler, webview_flutter, and Firebase plugins) may require special handling:

Permission Handler Configuration

When using permission_handler, ensure your Podfile modification follows this pattern:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
        '$(inherited)',
        # Add your permission flags here
        # 'PERMISSION_CAMERA=1',
        # 'PERMISSION_LOCATION=1',
      ]
    end
  end
end

Firebase Crashlytics Issues

Older versions of firebase_crashlytics (before 2.0.0) had known issues with this error. Consider updating to the latest version or using a maintained legacy fork if you cannot upgrade.

Architecture Exclusions

For M1 Mac users, adding arm64 to excluded architectures might help:

1. In Xcode, select your Runner target
2. Go to Build Settings
3. Search for "Excluded Architectures"
4. Add arm64 for both Debug and Release configurations
5. Repeat for Pods target

Full Disk Access for Xcode

On macOS, ensure Xcode has Full Disk Access:

1. Open System Settings → Privacy & Security → Full Disk Access
2. Enable Xcode in the application list

Prevention Strategies

1. Maintain consistent Flutter versions across development environments
2. Commit Podfile.lock to version control to ensure consistent dependency versions
3. Avoid manual modifications to iOS project files when possible
4. Regularly update plugins to maintain compatibility
5. Use the stable Flutter channel for production development

When All Else Fails

If none of the above solutions work, consider these nuclear options:

1. Create a completely new Flutter project and migrate your code
2. Check for specific plugin issues on GitHub and consider temporary removal to identify the culprit
3. Verify your Xcode installation is complete and updated

DANGER

Before trying radical solutions, ensure you have complete backups of your project and especially the iOS folder contents.

Conclusion

The "Flutter/Flutter.h file not found" error typically stems from iOS project misconfiguration rather than Flutter code issues. By methodically applying these solutions—starting with cache cleaning and dependency updates, then progressing to more invasive fixes—you can usually resolve the problem and return to productive development.