Introduction

The error "umbrella header ... not found" usually means Xcode is trying to build a framework module whose public-header setup does not match the file layout on disk. In mixed Swift and Objective-C frameworks, the umbrella header is the public entry point for exported Objective-C headers. In pure Swift frameworks, developers often run into this error because the project still contains an incorrect module map or header configuration that is no longer needed.

What the Umbrella Header Is For

In an Apple framework target, the umbrella header is the header that imports the framework's public Objective-C headers. It is typically named after the framework itself.

For example, if the framework is called MyFramework, the umbrella header is often:

1// MyFramework.h
2#import <Foundation/Foundation.h>
3
4FOUNDATION_EXPORT double MyFrameworkVersionNumber;
5FOUNDATION_EXPORT const unsigned char MyFrameworkVersionString[];
6
7#import <MyFramework/MyPublicClass.h>

That header becomes the entry point for Objective-C consumers of the framework and is part of the module definition.

Why the Error Happens

The failure usually comes from one of these situations:

• the header file was renamed or moved, but Xcode still points to the old path
• the header is not marked as Public in the target membership settings
• the module map references the wrong umbrella header
• the project is pure Swift, but leftover Objective-C framework configuration still expects a header that does not exist

That last case is common when a project started as a mixed-language framework and later became Swift-only.

Check the Target's Public Header Setup

For a mixed Swift and Objective-C framework, confirm that the umbrella header exists in the target and is exposed as a public header.

In Xcode, inspect the framework target's Build Phases and verify that the Headers phase marks the umbrella header and any exported Objective-C headers as Public.

If you are maintaining a custom module map, make sure it points to the correct file.

1framework module MyFramework {
2  umbrella header "MyFramework.h"
3  export *
4  module * { export * }
5}

If MyFramework.h is missing or located elsewhere, the build fails exactly as the error message suggests.

Pure Swift Frameworks Often Need Less Header Configuration

A pure Swift framework usually does not need a hand-maintained umbrella header for its Swift API. Swift modules are exposed through the Swift module system, not by importing a custom Objective-C umbrella header.

That means the right fix can be to remove stale header or module-map settings rather than to keep forcing a fake umbrella header into the target.

If you only added Objective-C compatibility temporarily and later removed all Objective-C files, check whether the project still contains:

• a custom module map
• an expected umbrella header filename in build settings
• bridging or public-header configuration that no longer matches the target

A Minimal Mixed-Language Check

If the framework really does expose Objective-C headers, the filesystem and target naming must line up. A clean minimal structure is:

1MyFramework/
2  MyFramework.h
3  MyPublicClass.h
4  MyPublicClass.m

And the umbrella header should import the public headers with the framework-style path.

#import <MyFramework/MyPublicClass.h>

If you import local files with the wrong relative path or the target name changed, the generated module can break.

Common Pitfalls

• Renaming the framework target without updating the umbrella header name or imports.
• Leaving a custom module map behind in a pure Swift framework.
• Forgetting to mark exported Objective-C headers as Public.
• Moving the umbrella header on disk without updating the project file.
• Trying to fix the error by adding random header search paths instead of correcting the module configuration.

Summary

• The umbrella header is the public Objective-C entry point for a framework module.
• The error usually means the header path, module map, or public-header configuration is wrong.
• Mixed Swift and Objective-C frameworks need consistent public-header setup.
• Pure Swift frameworks often do not need a manually managed umbrella header.
• Fix the module configuration itself instead of masking the problem with extra search paths.