Apple New Added 26 September 2026

ld: symbol(s) not found for architecture arm64

Compilation succeeded and the linker could not find a definition for something that was declared, so the reference survived to the link step. The architecture in the message is a red herring most of the time: a source file missing from the target, a library built for the other slice, or a C header included from C++ without extern "C" all report it this way.

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

Quick fix

# Which symbol, in human form
c++filt _Z3addii
# Xcode prints "Undefined symbols for architecture arm64" then the reference

# Does the library contain it, and for which slice
nm -gU /opt/homebrew/lib/libfoo.a | grep foo
lipo -info /opt/homebrew/lib/libfoo.dylib     # arm64, x86_64 or both

# A single slice library on Apple silicon needs a native rebuild
arch -arm64 make clean all

# C headers used from C++ need the linkage spelled out
extern "C" {
#include "legacy.h"
}

# Xcode: the file compiles but was never added to this target
# Build Phases, Compile Sources, and Other Linker Flags for -lfoo

# Homebrew is not on the default search path
export LDFLAGS="-L$(brew --prefix)/lib"
export CPPFLAGS="-I$(brew --prefix)/include"

How to diagnose Apple errors

macOS developer errors concentrate around three subsystems: the command line tools (xcrun and the active developer directory), the dynamic linker (dyld, library paths, and code signing), and Gatekeeper / notarisation. Apple Silicon added a fourth axis: architecture mismatches between arm64 and x86_64 binaries, which usually surface as confusing "library not loaded" or "bad CPU type" messages rather than as an explicit architecture error.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

Check the active developer directory first with xcode-select -p. After every macOS or Xcode update this can point at a path that no longer exists, breaking git, compilers and package managers all at once.
For dyld errors, run otool -L /path/to/binary to list what it actually wants, then verify each path exists. DYLD_PRINT_LIBRARIES=1 shows the resolution order at runtime.
Confirm architecture with file /path/to/binary and uname -m. On Apple Silicon, a Rosetta shell reports x86_64 and will silently install the wrong Homebrew prefix.
Homebrew lives at /opt/homebrew on Apple Silicon and /usr/local on Intel. Permission errors under /usr/local on an M-series Mac almost always mean a Rosetta/native mix-up.
For Gatekeeper and notarisation, use spctl -a -vvv to assess a bundle and xcrun notarytool log to get the actual rejection reason. The submission status alone tells you nothing useful.

Tools worth reaching for

xcode-select -p
otool -L
codesign -dv --verbose=4
spctl -a -vvv
xcrun notarytool log

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

developer.apple.com developer.apple.com

Related Apple errors

See all 20 Apple errors →

Browse other categories

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.