How to Fix ‘Symbol(s) not found for architecture arm64’ in Xcode

When Xcode fails during the final link step with “Symbol(s) not found for architecture arm64” or a similar “Symbols not found for architecture arm64” message, the source code may have compiled successfully but the linker could not find one or more required functions, variables, classes, or other symbols for the arm64 build.

What the error means

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

arm64 is widely used by current iPhone and iPad devices and Apple silicon Macs. The message does not usually mean that arm64 itself is the problem. It means that while linking the arm64 binary, Xcode could not resolve the implementation of a symbol referenced by your code or one of its dependencies.

Common causes

• A required .framework, .xcframework, or .a library is not linked to the target.
• A source file is missing from the target’s Target Membership.
• An Objective-C, C, or C++ implementation file is missing from Compile Sources.
• A Swift Package Manager or CocoaPods dependency is not integrated correctly.
• A prebuilt library does not contain an arm64 slice.
• A declaration and its implementation do not match.
• Required linker settings such as Other Linker Flags are missing.
• Stale DerivedData or other build artifacts are interfering with the link step.

Typical situations

This error often appears after adding a third-party SDK, migrating between CocoaPods and Swift Package Manager, switching from a Simulator build to a physical device, or moving a project to an Apple silicon Mac. If the Simulator build succeeds but the device build fails, verify that every prebuilt dependency includes an iOS arm64 slice.

How to diagnose the problem

1. Read the undefined symbol shown immediately above the final error

The most useful information is usually several lines above “Symbol(s) not found.” Identify the exact undefined symbol and the object file that references it.

Undefined symbols for architecture arm64:
  "_ExampleFunction", referenced from:
      ...
Symbol(s) not found for architecture arm64

2. Check Build Phases

Select the app target and open Build Phases. Inspect both “Link Binary With Libraries” and “Compile Sources.” Make sure the required frameworks, libraries, and implementation files are present.

3. Check Target Membership

Select the source file in the Project navigator and open the File inspector. Confirm that the intended target is enabled under Target Membership. A header or declaration can be visible to the compiler even when its implementation file is not actually built into the target.

4. Check the architectures in a prebuilt binary

For a framework or static library, use lipo to inspect its architectures:

lipo -info /path/to/YourLibrary.framework/YourLibrary

For an XCFramework, confirm that the package includes an iOS device variant containing arm64.

Fix 1: Link the required framework or library

Open Target → Build Phases → Link Binary With Libraries and verify that the dependency providing the missing symbol is listed. If it is missing, add it with the “+” button.

Dragging an SDK into the project navigator does not always complete every required link setting, especially with manually distributed frameworks and libraries.

Fix 2: Correct Target Membership and Compile Sources

If the missing symbol belongs to your own code, enable the correct Target Membership for the implementation file. Also check Build Phases → Compile Sources and make sure the implementation is part of the target.

Fix 3: Resolve Swift Package dependencies again

If the missing symbol comes from a Swift package, confirm that the package product is attached to the correct target. You can also force package dependency resolution from the command line:

xcodebuild -resolvePackageDependencies

Fix 4: Reinstall CocoaPods dependencies

For a CocoaPods-based project, refresh the Pod integration:

pod install --repo-update

When CocoaPods generates a workspace, open the .xcworkspace rather than the .xcodeproj for normal builds.

Fix 5: Confirm that the dependency supports arm64

Older static libraries and frameworks may not contain an arm64 slice. In that case, update to a newer SDK or XCFramework distribution when available. Xcode build settings such as Architectures determine which CPU architectures a target is built for.

xcodebuild -showBuildSettings | grep -E "ARCHS|EXCLUDED_ARCHS"

Fix 6: Check Other Linker Flags

Some static libraries, including certain Objective-C libraries that contain categories, require linker flags documented by the SDK vendor. A common example is:

-ObjC

Do not add linker flags at random. Extra flags can introduce different link problems. Follow the documentation for the specific library or SDK that provides the missing symbol.

Fix 7: Clear DerivedData and rebuild

After correcting the project configuration, remove stale build artifacts if the old link state continues to appear:

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

Then use Product → Clean Build Folder in Xcode and build again.

Important notes

Excluding arm64 can sometimes make one configuration build temporarily, but it is not a general fix for an iOS device build where arm64 is required. The better approach is to identify the missing implementation or replace an incompatible dependency.

Summary

The Xcode “Symbol(s) not found for architecture arm64” error means the linker cannot resolve one or more required symbols for the arm64 output. Start with the undefined symbol listed above the final error, then check Link Binary With Libraries, Compile Sources, Target Membership, package integration, and the architecture support of prebuilt dependencies. After correcting the configuration, clearing DerivedData and rebuilding can remove stale intermediate results.