Xcode「Linker command failed with exit code 1」の原因と解決方法

clang: error: linker command failed with exit code 1 (use -v to see invocation)

Linker command failed with exit code 1

What does “Linker command failed with exit code 1” mean?

Xcode first compiles Swift, Objective-C, C, and C++ source files into object code.

The linker then combines those object files with frameworks and libraries to create the final executable or framework binary.

If that process fails, Xcode eventually reports:

clang: error: linker command failed with exit code 1

Because many different linker problems can lead to the same final message, the preceding error is the useful part.

What to check first

Open Xcode’s Report Navigator and expand the failed Link or Ld step.

For example:

Undefined symbols for architecture arm64: "_OBJC_CLASS_$_SomeClass", referenced from: ...

ld: symbol(s) not found for architecture arm64
clang: error: linker command failed with exit code 1

The real problem here is the undefined symbol.

Another example:

duplicate symbol '_someFunction' in: FileA.o FileB.o

ld: 1 duplicate symbol
clang: error: linker command failed with exit code 1

Here, the duplicate symbol is the root cause.

Common causes

1. Undefined symbols

Undefined symbols for architecture arm64: "_SomeFunction", referenced from: ...

Your code references a class or function whose implementation the linker cannot find.

2. Duplicate symbols

duplicate symbol '_someFunction' in: FileA.o FileB.o

The same symbol is being defined more than once.

3. Framework not found

ld: framework 'SomeFramework' not found

4. Library not found

ld: library 'SomeLibrary' not found

5. A required framework or library is not linked

The dependency may exist in the project but not in the affected target’s Link Binary With Libraries phase.

6. A Swift Package product is not attached to the target

The package may be present while the specific product that provides the required symbols is missing from the target.

7. CocoaPods integration is incomplete

You may be opening the .xcodeproj instead of the .xcworkspace, or the Podfile may be configured for a different target.

8. A source file is not included in Target Membership

The implementation exists in the project but is not compiled into the target.

9. An implementation file is missing from Compile Sources

This is common with Objective-C, C, and C++ sources.

10. A C or C++ function was declared but never implemented

The compiler sees the declaration but the linker cannot find the definition.

11. A C++ signature does not match

Different parameter types, namespaces, references, or const qualifiers produce different symbols.

12. Objective-C code should be compiled as Objective-C++

A source file that directly uses C++ may need the .mm extension instead of .m.

13. A binary framework does not support the required architecture

An older framework may not contain arm64 or another architecture required by the destination.

14. An XCFramework is missing the required platform slice

iOS device arm64 and iOS Simulator arm64 are different platform binaries.

15. Required linker flags are missing

Some Objective-C static-library configurations may require -ObjC.

16. Old linker flags are still present

Obsolete library names, -force_load paths, or custom flags can break the link.

17. Debug and Release use different linker settings

This is a common reason why normal builds succeed while Archive fails.

18. Library Search Paths are incorrect

A manually integrated static library may not be found.

19. Framework Search Paths are incorrect

Xcode may be unable to locate a custom framework.

20. A static library has another dependency

Library A may reference symbols from Library B, requiring Library B to be linked into the final target as well.

Typical situations where the error appears

• After adding a framework
• After adding or updating a Swift Package
• After updating CocoaPods
• After integrating Objective-C or C++ code
• After moving a source file to another target
• After changing Target Membership
• After adding a new function or class
• After integrating a static library
• After replacing a framework with an XCFramework
• After switching from Simulator to a physical device
• After upgrading Xcode
• When Debug works but Archive fails

Solution 1: Find the first linker error

Open:

Report Navigator → Failed Build → Link / Ld

Look above:

clang: error: linker command failed with exit code 1

Search for messages such as:

• Undefined symbols
• duplicate symbol
• framework not found
• library not found
• file was built for
• building for iOS Simulator
• architecture arm64

Solution 2: Fix undefined symbols

For example:

Undefined symbols for architecture arm64: "_OBJC_CLASS_$_SomeClass"

Determine where SomeClass should come from.

For your own source code, inspect Target Membership and Compile Sources.

For external code, inspect Link Binary With Libraries, Swift Package products, or CocoaPods dependencies.

Solution 3: Fix duplicate symbols

duplicate symbol '_calculateValue' in: FileA.o FileB.o

Make sure the same function or global variable is not defined in multiple files.

Incorrect:

// FileA.c int globalValue = 10;

// FileB.c
int globalValue = 10;

Declare it in a header:

// Globals.h extern int globalValue;

Define it once:

// Globals.c int globalValue = 10;

Solution 4: Check Link Binary With Libraries

Open:

Project → TARGETS → Affected Target → Build Phases → Link Binary With Libraries

Verify that the required framework, XCFramework, static library, or package product is listed.

Solution 5: Check Swift Package products

For Package.swift:

.target( name: "MyApp", dependencies: [ .product( name: "SomeLibrary", package: "SomePackage" ) ] )

Make sure the exact product used by the application is attached to the correct target.

Solution 6: Open the CocoaPods workspace

Run:

pod install

Then open:

MyApp.xcworkspace

Do not build only the original .xcodeproj when the Pods integration depends on the workspace.

Solution 7: Check Target Membership

File Inspector → Target Membership → Enable the affected target

Make sure implementation files that provide the missing symbols belong to the target.

Solution 8: Check Compile Sources

Target → Build Phases → Compile Sources

Verify that required .m, .mm, .c, and .cpp files are present.

Solution 9: Check declarations and definitions

If a header declares:

int calculate(int value);

there must be an implementation:

int calculate(int value) { return value * 2; }

Solution 10: Verify C++ signatures

These are different symbols:

void calculate(int value); void calculate(double value);

Namespaces also matter:

namespace A { void calculate(); }

namespace B {
void calculate();
}

Solution 11: Rename .m to .mm when using C++

SomeFile.m ↓ SomeFile.mm

This tells Xcode to compile the file as Objective-C++.

Solution 12: Verify supported architectures

For a static library:

lipo -info path/to/libExample.a

For a framework:

lipo -info Example.framework/Example

Solution 13: Inspect XCFramework slices

Example.xcframework/ ios-arm64/ ios-arm64_x86_64-simulator/

Verify that the current build destination has a matching slice.

Solution 14: Use nm to locate symbols

For a static library:

nm -gU path/to/libExample.a | grep SomeFunction

For a framework:

nm -gU Example.framework/Example | grep SomeClass

If the expected symbol does not exist, the binary may not contain the required implementation.

Solution 15: Check Framework Search Paths

xcodebuild -showBuildSettings | grep FRAMEWORK_SEARCH_PATHS

Solution 16: Check Library Search Paths

xcodebuild -showBuildSettings | grep LIBRARY_SEARCH_PATHS

Solution 17: Check Other Linker Flags

xcodebuild -showBuildSettings | grep OTHER_LDFLAGS

Some Objective-C static-library configurations may require:

-ObjC

Solution 18: Remove obsolete linker flags

Review old settings such as:

• -force_load
• -all_load
• -lSomeLibrary
• -framework SomeFramework

Remove or correct references to libraries that no longer exist.

Solution 19: Link dependencies of static libraries

If:

App ↓ Library A ↓ Library B

Library A references Library B, the final app may need Library B linked as well.

Solution 20: Compare Debug and Release

xcodebuild -showBuildSettings -configuration Debug | grep -E "OTHER_LDFLAGS|FRAMEWORK_SEARCH_PATHS|LIBRARY_SEARCH_PATHS"

xcodebuild -showBuildSettings -configuration Release | grep -E "OTHER_LDFLAGS|FRAMEWORK_SEARCH_PATHS|LIBRARY_SEARCH_PATHS"

Look for Release-only differences.

Solution 21: Check Architectures and Excluded Architectures

ARCHS EXCLUDED_ARCHS

Old workarounds such as:

EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64

should be reviewed to confirm they are still necessary.

Solution 22: Inspect the actual linker invocation

Expand the Link step in Xcode’s Report Navigator.

Check:

• Framework arguments
• Library arguments
• -F framework search paths
• -L library search paths
• Architecture
• Other linker flags

Solution 23: Clean the build folder

After fixing the configuration:

Product → Clean Build Folder

Solution 24: Remove DerivedData if necessary

rm -rf ~/Library/Developer/Xcode/DerivedData/*

If the error says “Undefined symbols”

Undefined symbols for architecture arm64: "_SomeFunction"

Identify which source file or dependency should provide SomeFunction.

Check:

• Link Binary With Libraries
• Target Membership
• Compile Sources
• Swift Package products
• CocoaPods target configuration
• XCFramework slices

If the error says “duplicate symbol”

Common causes include:

• The same source file is included twice
• The same static library is linked through multiple paths
• A global variable is defined in multiple files
• An implementation .m file is imported directly

// Avoid #import "SomeClass.m"

// Normally use
#import "SomeClass.h"

If the error says “framework not found”

ld: framework 'SomeFramework' not found

Check:

• Whether the framework exists
• Framework Search Paths
• Swift Package resolution
• CocoaPods workspace integration
• Configuration-specific paths

If the error says “library not found”

ld: library 'SomeLibrary' not found

Check:

• Whether the library file exists
• Library Search Paths
• -l entries in Other Linker Flags
• Whether the library was renamed

If Archive alone fails

Focus on the Release configuration:

• Framework Search Paths
• Library Search Paths
• Other Linker Flags
• Swift Package products
• Release xcconfig files
• Architectures
• Excluded Architectures

If Simulator alone fails

Check whether the binary dependency contains a Simulator-compatible slice.

On Apple Silicon, iOS Simulator commonly uses arm64, but device arm64 and Simulator arm64 are still different platforms.

If a physical device alone fails

Make sure the XCFramework contains a physical iOS device slice such as:

Example.xcframework/ ios-arm64/

If the problem started after adding CocoaPods

1. Run pod install.
2. Open the .xcworkspace.
3. Verify the Podfile target.
4. Check Pods xcconfig integration.
5. Check Link Binary With Libraries.
6. Clean the build folder last.

If the problem started after adding a Swift Package

1. Verify that package resolution succeeded.
2. Attach the required product to the affected target.
3. Check the product’s platform requirements.
4. For binary targets, inspect XCFramework slices.
5. Compare Debug and Release.

What you should avoid

That line is the result of the failure, not the cause.

Also avoid randomly adding -ObjC, -all_load, -force_load, or excluding arm64 without identifying the actual linker error first.

Fast troubleshooting checklist

1. Read the error immediately before the final linker failure.
2. Determine whether it is an undefined symbol or duplicate symbol.
3. Check for missing frameworks or libraries.
4. Inspect Link Binary With Libraries.
5. Check Target Membership and Compile Sources.
6. Verify Swift Package products.
7. For CocoaPods, open the workspace.
8. Check Framework and Library Search Paths.
9. Verify XCFramework platform and architecture slices.
10. Inspect Other Linker Flags.
11. Compare Debug and Release.
12. Clean caches only after fixing the configuration.

Summary

“Linker command failed with exit code 1” is a generic Xcode error indicating that the final link step failed after compilation.

The most important diagnostic step is to inspect the first linker-specific error immediately before the final message.

Common causes include undefined symbols, duplicate symbols, missing frameworks or libraries, incorrect Swift Package or CocoaPods dependencies, Target Membership issues, missing Compile Sources, incorrect search paths, linker flags, and incompatible XCFramework platform or architecture slices.

Identify the missing or duplicated symbol or library first, then inspect the dependency that should provide it. This is far more effective than randomly changing build settings or repeatedly deleting DerivedData.