Swift "linker command failed" in CI

Compilation succeeded but linking failed. The linker could not resolve symbols or locate a library needed to produce the final binary.

What this error means

The build fails with linker command failed with exit code 1, usually preceded by Undefined symbols or library not found. It is usually deterministic; occasional flaky link failures are transient.

swift

Undefined symbols for architecture arm64:
  "_OBJC_CLASS_$_CLLocationManager", referenced from: ...
ld: symbol(s) not found for architecture arm64
clang: error: linker command failed with exit code 1

Common causes

Missing system framework or library

Code uses a framework (CoreLocation, a C library) that is not linked, so its symbols are undefined.

Architecture or SDK mismatch

A prebuilt binary or library was built for a different architecture than the build target.

Transient link failure

Rarely, a flaky toolchain or interrupted I/O makes a link step fail; a re-run succeeds.

How to fix it

Link the required framework

Declare the system library the target needs.

Package.swift

.target(
  name: "App",
  linkerSettings: [.linkedFramework("CoreLocation")])

Match architecture and SDK

Confirm prebuilt binaries match the build architecture.
Use an xcframework for multi-arch dependencies.
Build against the SDK the runner ships.

Re-run on transient link failures

A rare flaky link error usually clears on retry; Latchkey managed runners auto-retry such transient failures.

How to prevent it

Link all required frameworks explicitly.
Use xcframeworks for binary dependencies.
Keep SDK and architecture consistent.