macOS runner: "ld: library not found for -lSystem" in CI

The macOS linker resolves -lSystem from the active SDK library directory. When the SDK path is stale or the Command Line Tools are missing, ld cannot find libSystem and the link step fails.

What this error means

A native compile or link (often a Ruby gem, Node native module, or Go cgo build) fails with "ld: library not found for -lSystem" and "clang: error: linker command failed".

ld: library not found for -lSystem
clang: error: linker command failed with exit code 1 (use -v to see invocation)

Common causes

The Command Line Tools SDK path is stale

After an OS or Xcode change the active developer directory points at an SDK that no longer holds the system libraries, so -lSystem cannot resolve.

A missing SDKROOT or library search path

The build does not pass the current SDK, so ld searches a path without libSystem.tbd and reports it as not found.

How to fix it

Point the toolchain at the current SDK

1. Reset xcode-select or select a valid Xcode.
2. Export SDKROOT to the active SDK so ld searches the right library directory.
3. Rebuild.

sudo xcode-select --reset
export SDKROOT="$(xcrun --show-sdk-path)"
clang main.c -o app

Reinstall Command Line Tools

If the CLT bundle is incomplete, reinstalling restores the SDK and libSystem the linker needs.

sudo rm -rf /Library/Developer/CommandLineTools
sudo xcode-select --install

How to prevent it

• Export SDKROOT from xcrun --show-sdk-path for native builds.
• Select a known-good Xcode version at the start of the job.
• Verify xcrun --find ld before heavy native compilation.

Related guides