Fix: CocoaPods header file not found in Xcode

Written by

in

Quick answer: Check that the target producing the error has the pod in its Podfile target block and uses the CocoaPods-generated configuration. Then ensure its Header Search Paths setting includes $(inherited), run pod install, and build the .xcworkspace.

Why this happens

An error such as ASLogger/ASLogger.h file not found means the compiler cannot find the header requested by an import. With CocoaPods, that can happen even when the dependency has been installed: the target being built may not use the CocoaPods configuration, or its own build settings may override the search paths supplied by that configuration.

This often becomes visible after switching branches or building a different target, such as a development app or test target. Installing pods again does not necessarily fix a target that is missing the dependency or has a conflicting configuration.

How to fix it

1. Check the affected target’s configuration

Start with the target named in Xcode’s build error. An app, its tests, and a separate development app can each have different build configurations.

  1. Select the project in Xcode’s project navigator.
  2. Select the project in the editor and open the Info tab.
  3. Under Configurations, expand the build configuration that failed, such as Debug.
  4. Find the row for the affected target and check which configuration file it uses.
  5. If the target has no configuration file and does not need a custom one, select the appropriate CocoaPods-generated configuration for that target and build configuration.
  6. Check the other configurations you use, including Release, rather than assuming they have the same setup.

CocoaPods generates configuration files in Pods/Target Support Files. Their names depend on the integrated target and configuration. Choose the file for the actual target and configuration; do not assign a Debug file to Release just because it makes one build succeed.

If your target already uses a custom .xcconfig, do not replace it without checking what it contains. Include the generated CocoaPods file from your custom configuration instead, as described below.

2. Add the pod to every target that needs it

Open the Podfile and confirm that the dependency is declared for the target compiling the failing source file. A separate app target does not automatically receive another target’s pods just because both targets are in the same Xcode project.

For example, if both MyApp and MyApp Dev directly use the header, their Podfile could contain:

target 'MyApp' do
  pod 'ASLogger'
end

target 'MyApp Dev' do
  pod 'ASLogger'
end

Replace the target names and dependency with those in your project. Keep any existing version requirements or other Podfile settings your project needs.

From the directory containing the Podfile, run:

pod install

Then open the generated .xcworkspace and build the affected target again. If the problem is in a test target, check that target’s Podfile configuration too; its dependency requirements may differ from those of the app target.

Older CocoaPods examples may use link_with to list multiple targets. For a current Podfile, use explicit target blocks rather than copying that historical syntax.

3. Preserve inherited header search paths

A target-level Header Search Paths value can override paths supplied by the CocoaPods configuration. Add $(inherited) so Xcode can also use values inherited from lower levels of the build settings.

  1. Select the affected target in Xcode.
  2. Open Build Settings and search for Header Search Paths.
  3. Inspect the value for the configuration that fails.
  4. If the target defines its own paths, add $(inherited) to that list. Keep any paths the project still needs.
  5. Build again and check whether the header error has changed.

You can also inspect the resolved build setting in Xcode to see which paths are being used. Adding $(inherited) helps only when the necessary paths are available from the target’s configuration; it does not add a missing pod to the Podfile.

4. Include CocoaPods settings in a custom configuration

Projects that use their own .xcconfig files need to retain those settings while also incorporating the CocoaPods-generated configuration. Add an include to the custom file used by the affected target and build configuration.

For example, if MyApp-Debug.xcconfig is in the same directory as Pods, and CocoaPods generated the indicated file, it could contain:

#include "Pods/Target Support Files/Pods-MyApp/Pods-MyApp.debug.xcconfig"

This is an example path, not a universal filename. Find the generated file for your target, make the include path relative to your custom .xcconfig, and use the matching file for each configuration. A Release configuration should include its corresponding Release settings.

After editing the files, verify under Project → Info → Configurations that the target still uses your custom configuration. Then build the affected target. If the include cannot be found, check the path and confirm that pod install generated the referenced file.

5. Verify the workspace and import

If the configuration and search paths look correct but the error remains, check the remaining basics:

  1. Open the .xcworkspace, not just the .xcodeproj, when building the CocoaPods-integrated project.
  2. Confirm that the import matches a public header provided by the installed dependency. For the example error, the failing import may look like #import <ASLogger/ASLogger.h>.
  3. Compare the branch’s Podfile and Podfile.lock with the versions expected by the project. Run pod install after changing branches if the dependency setup changed.
  4. Read the first header-related error in the build log and confirm which target and source file produced it. Fix that target rather than changing settings across the entire project without a reason.

Avoid deleting Podfile.lock as a first troubleshooting step. It records resolved dependency versions, and removing it can change more than the configuration problem you are trying to diagnose.

How to prevent it

  • Add dependencies to the Podfile target blocks that need them.
  • Check CocoaPods configuration integration when adding app variants or custom build configurations.
  • Preserve $(inherited) when setting target-level header search paths.
  • Keep custom .xcconfig includes matched to their target and build configuration.
  • Run pod install when the checked-out branch changes the project’s pod setup, and build from the workspace.

FAQ

Why does one target build while another cannot find the same header?

Each target can have different pod dependencies, configuration files, and build settings. Compare the failing target with the working target, then check its Podfile block and configuration assignment.

Does $(inherited) install the missing pod?

No. It preserves values inherited from other build-setting levels. The pod still needs to be declared and installed for the target, and the target needs access to the CocoaPods configuration.

Should I replace my custom .xcconfig with the CocoaPods file?

Not if your custom file contains settings the project needs. Include the appropriate generated CocoaPods configuration in the custom file and keep the custom file assigned to the target.

Sources & credits

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