Cargo "failed to run custom build command" in CI

A crate ran a build script (build.rs) and it exited non-zero. The wrapper line names the crate; the actual reason -- a missing system library, a missing tool, or a script error -- is in the captured --- stderr output below it.

What this error means

cargo fails with error: failed to run custom build command for X v1.2.3` followed by a process didn't exit successfully line and a --- stdout / --- stderr block. It is common for -sys` crates that probe for native dependencies.

cargo

error: failed to run custom build command for `zstd-sys v2.0.9`

Caused by:
  process didn't exit successfully: `.../build-script-build` (exit status: 101)
  --- stderr
  thread 'main' panicked at 'Unable to find libclang'

Common causes

A native dependency or tool is missing

The build script probes for a system library or tool (libclang, pkg-config, cmake, a compiler) and panics when it cannot find it on a minimal runner.

The build script itself errored

The script hit a runtime error -- a failed command, a bad environment variable, or a network call it was not allowed to make -- and returned a non-zero exit code.

How to fix it

Read the stderr block and install what it needs

Scroll to the --- stderr section -- it states exactly what the script could not find or do.
Install the missing tool or library (e.g. pkg-config, cmake, clang/libclang-dev).
Set any env var the script expects (such as LIBCLANG_PATH or <NAME>_DIR).

Install common native build deps

Terminal

# Debian/Ubuntu, typical -sys prerequisites
apt-get update && apt-get install -y \
  pkg-config cmake clang libclang-dev build-essential

How to prevent it

Bake the native build tools your -sys crates need into the runner image.
Pin -sys crate versions so their probing behavior stays predictable.
On Latchkey managed runners, build-script dependencies can be pre-resolved and cached so cold builds do not fail probing for native tools.