ld: library not found for -lSystem" after macOS SDK upgrade in CI - how to fix

TL;DR: The macOS SDK upgrade moved the SDK, but the linker is still pointed at the old location, so it cannot find the system library. Reinstall the Command Line Tools and reset the active developer directory with xcode-select. Then export SDKROOT from xcrun so the linker uses the current SDK.

ld: library not found for -lSystem

1. Check where the tools currently point: xcode-select -p. Expected: a path is printed; if it names an Xcode or SDK version that no longer exists, that is the cause.

2. Reset the developer directory: sudo xcode-select --reset. Expected: no output; the path now resolves to the installed tools.

3. Reinstall the Command Line Tools: xcode-select --install. Expected: the installer runs to completion.

4. Point the build at the current SDK: export SDKROOT=$(xcrun --show-sdk-path), then rebuild. Expected: xcrun prints a valid SDK path and the link step succeeds.

5. If CI exports a stale DEVELOPER_DIR, unset it before the build step. Expected: xcode-select -p shows the fresh path and the -lSystem error is gone.

Use this when

• The link fails with the exact "library not found for -lSystem" message.
• The failure started after a macOS, Xcode, or Command Line Tools upgrade.
• CI runners cache toolchains across macOS image updates.

Not for this skill when

• The missing library is a third-party one (-lssl, -lpq); install that library instead.
• The error is about an iOS SDK rather than the macOS SDK.
• The failure is a codesigning or notarization error; linking already succeeded.

Variant phrasings

• "ld library not found for -lSystem xcode"
• "clang ld lSystem missing after macOS update"
• "library not found for -lSystem command line tools"
• "ld: library not found for -lSystem github actions macos"

Why it happens

-lSystem links libSystem from the macOS SDK. Upgrades install the SDK at a new path and remove the old one, but xcode-select, cached DEVELOPER_DIR values, or exported SDKROOT variables keep pointing the linker at the deleted location. The library is present on the machine; only the pointer is stale.

Edge cases

• GitHub Actions macos runners already ship the tools; a reset is usually enough without a reinstall.
• With multiple Xcode versions installed, use sudo xcode-select -s [Xcode path] to pick the right one explicitly.
• Apple Silicon and Intel runners keep SDKs in different locations; do not copy SDKROOT between architectures.
• Some build systems cache the SDK path in their own config; clear that cache after resetting.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstHowJUmEgySrY07BeAPWCw