Fix: Swift pods cannot be integrated as static libraries in CocoaPods

Fix: Swift pods cannot be integrated as static libraries in CocoaPods

Written by

in

Quick answer: Enable modular headers for the dependency CocoaPods says does not define modules—for this error, add pod 'GoogleUtilities', :modular_headers => true inside the affected app target in your Podfile. Run pod install again, and avoid changing framework linkage or deleting Podfile.lock unless a separate requirement calls for it.

Why this happens

CocoaPods stops installation when a Swift pod needs to import an Objective-C dependency that does not expose a module in the selected integration configuration. The relevant diagnostic is:

[!] The following Swift pods cannot yet be integrated as static libraries:

The Swift pod `FirebaseCoreInternal-library` depends upon
`GoogleUtilities-library`, which does not define modules.

In this dependency chain, FirebaseCoreInternal needs to import GoogleUtilities. A module map describes the headers that belong to an importable module. CocoaPods can generate that module map when modular headers are enabled for the dependency.

This is a CocoaPods integration problem, not a Swift syntax error. Repeating pod install --repo-update or running pod update does not directly fix a missing module configuration. Flutter and React Native projects can both encounter it because their iOS dependencies are ultimately integrated through CocoaPods.

How to fix it

1. Enable modular headers for the named dependency

Open ios/Podfile and find the application target. For a typical Flutter project, that target is Runner.

Add the modular-header declaration inside that target, alongside the existing dependency installation code:

target 'Runner' do
  pod 'GoogleUtilities', :modular_headers => true

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

This is a target excerpt, not a replacement for the complete Flutter Podfile. Keep the existing Flutter setup, build settings, and post_install hook.

If the Podfile already declares GoogleUtilities, edit that declaration instead of adding a conflicting second one. Preserve any existing version constraint or source option.

Then run:

cd ios
pod install

Use the dependency name GoogleUtilities in the Podfile, not GoogleUtilities-library. The latter appears in the reported integration diagnostic; it is not the pod declaration shown in the working solutions.

Start with the dependency explicitly identified as lacking modules. If installation reports another dependency with the same problem, evaluate that named dependency next rather than adding modular-header overrides to every pod.

2. Apply the broader Firebase override when needed

The accepted solution enables modular headers for several Firebase-related pods:

pod 'Firebase', :modular_headers => true
pod 'FirebaseCoreInternal', :modular_headers => true
pod 'GoogleUtilities', :modular_headers => true
pod 'FirebaseCore', :modular_headers => true

Place the relevant declarations inside the affected application target. This broader approach can be useful when the installed Firebase dependency graph requires more than the single GoogleUtilities adjustment.

However, do not automatically add all four declarations to every project. Flutter and React Native integrations commonly bring Firebase dependencies into the project through their own installation helpers. Explicitly adding a root pod such as Firebase can affect dependency resolution, so keep the override limited to dependencies your integration actually uses.

After each change, run pod install and read the new result. If the original module error disappears but CocoaPods reports incompatible version requirements, treat that as a separate dependency-resolution problem. Adding more modular-header declarations will not resolve contradictory version constraints.

The source examples also change the iOS deployment target. That change is not what generates module maps. Keep a deployment target supported by your installed dependencies, but do not copy an old deployment-target value as a fix for this diagnostic.

3. Check existing global settings before changing linkage

The reported Flutter Podfile already contains both:

use_frameworks!
use_modular_headers!

If yours does too, do not add another copy of either directive. Check that you are editing the Podfile used by the failing installation and that the directives apply to the affected target. In a multi-target Podfile, their placement and target inheritance matter.

CocoaPods offers two relevant modular-header configurations:

  • use_modular_headers! applies modular headers broadly to CocoaPods static libraries in its scope.
  • :modular_headers => true opts a particular pod into modular headers.

The targeted setting is the narrower starting point when the diagnostic names one dependency. A global setting changes header handling for more pods and can expose unrelated integration issues.

Do not treat use_frameworks! as another spelling of modular headers. It changes how CocoaPods packages dependencies. Removing it may affect other plugins, while adding it may conflict with tooling in the project. Keep the linkage configuration required by your particular Flutter or React Native integration unless you have a separate reason to change it.

4. Keep the React Native and Flipper workaround separate

The highly voted React Native solution uses modular-header declarations for Firebase, FirebaseCore, and GoogleUtilities while retaining an existing Flipper setup. It avoids enabling use_frameworks! in that configuration because the Flipper integration conflicts with it.

That answer also includes:

$RNFirebaseAsStaticFramework = true

This is a React Native Firebase integration variable, not a general CocoaPods option. Do not add it to a Flutter Podfile to solve a GoogleUtilities module error. In React Native projects, use it only when required by the setup instructions for your installed React Native Firebase configuration.

Likewise, do not copy an old React Native Podfile wholesale. Its Flipper helpers, architecture settings, and platform workarounds belong to that project’s toolchain. Transfer the targeted modular-header fix, not unrelated configuration.

5. Verify the fix without upgrading everything

From the iOS directory, run:

pod install

If the project manages CocoaPods through Bundler, use its configured environment:

bundle exec pod install

A successful installation confirms that CocoaPods has passed the dependency integration stage. Next, build through your normal Flutter or React Native workflow. If opening the iOS project directly in Xcode, use the generated .xcworkspace so the app includes its Pods integration.

Keep Podfile.lock while diagnosing this issue. Deleting it or running an unrestricted pod update can change dependency versions and make it harder to tell whether modular headers fixed the original problem. Review the resulting Podfile and lockfile changes before committing them.

How to prevent it

  • Make narrowly scoped Podfile changes and keep framework linkage unchanged unless required.
  • Commit Podfile.lock so collaborators resolve the same dependency versions.
  • Follow Firebase integration instructions that match your installed Flutter or React Native packages.
  • Avoid copying Flipper settings or React Native variables into Flutter projects.
  • Read the exact dependency named in each CocoaPods diagnostic instead of applying a growing list of overrides blindly.

FAQ

Should I use use_modular_headers! or per-pod modular headers?

Start with per-pod modular headers when one dependency is identified. The global directive is broader and may be appropriate for an integration that explicitly requires it, but it changes header handling for more dependencies.

Do I need to remove use_frameworks!?

Not necessarily. The accepted workaround avoids it in a configuration involving Flipper, but that does not make removal correct for every Flutter or React Native app. Check what your other dependencies require before changing linkage.

Why does pod install --repo-update still fail?

Updating pod specifications does not directly change whether a dependency generates a module map. Correct the Podfile’s modular-header configuration first; refresh specifications only when the installation also reports a specification availability problem.

Sources & credits

Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.