node-gyp "No Xcode or CLT version detected" on macOS CI
node-gyp needs Apple’s Command Line Tools to compile native addons on macOS. On a runner without them - or with a stale CLT receipt - the build aborts before compiling. Often you can avoid compiling entirely.
What this error means
On a macOS runner, installing a package with a native addon fails with No Xcode or CLT version detected! from node-gyp. Linux runs of the same install succeed because they have a toolchain and prebuilt binaries.
gyp: No Xcode or CLT version detected!
gyp ERR! configure error
gyp ERR! stack Error: `gyp` failed with exit code: 1Common causes
Command Line Tools missing or stale on the runner
macOS needs the Xcode Command Line Tools for node-gyp. A fresh or updated macOS image without them - or with a broken CLT receipt after an OS bump - fails the configure step.
Building from source when a prebuilt exists
Many native packages ship prebuilt macOS binaries. Forcing a source build (or a missing prebuilt for that arch) drags node-gyp in when it was avoidable.
How to fix it
Prefer a prebuilt binary (avoid compiling)
Most native packages download a prebuilt for the platform when one exists, so node-gyp never runs. Ensure scripts are not disabled and the arch matches.
# let prebuilt binaries install (do not pass --ignore-scripts)
npm ci
# Apple Silicon vs Intel: install the matching arch binaryInstall the Command Line Tools when you must build
If a source build is unavoidable, ensure the CLT are present on the macOS runner.
xcode-select --install || true
xcode-select -p # confirm the toolchain pathHow to prevent it
- Prefer packages with prebuilt macOS binaries so node-gyp never runs.
- Keep the Command Line Tools installed on self-hosted macOS runners.
- Match the runner architecture (arm64 vs x64) to the prebuilt binaries.