Rust "failed to run custom build command for X" in CI

A crate’s build.rs build script exited non-zero. The wrapper line names the crate; the actual error - a missing tool, a failed cc compile, or a panic - is in the script output printed just above.

What this error means

cargo fails with error: failed to run custom build command for <crate> followed by the script’s stdout/stderr and a process didn't exit successfully line. The pure-Rust crates compiled; only this crate’s build step failed.

cargo output

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

Caused by:
  process didn't exit successfully: `/app/target/debug/build/zstd-sys-.../build-script-build` (exit status: 1)
  --- stderr
  thread 'main' panicked at 'Unable to find libclang: ...'

Common causes

A tool the build script needs is missing

Build scripts often invoke cc, cmake, clang/libclang (for bindgen), protoc, or perl. If the runner lacks it, the script panics or exits non-zero.

The script’s own compile or codegen failed

A -sys crate compiles bundled C/C++ in build.rs. A missing header, wrong toolchain, or unsupported flag makes that inner compile fail and the script exit 1.

How to fix it

Read the script’s stderr for the real cause

Scroll into the --- stderr block - that is the actual error, not the wrapper line.
Map the missing tool (libclang, cmake, protoc, perl) to its package and install it.
Re-run with cargo build -vv to see the full build-script command and output.

Install the build-time dependency

Provide the tool the script needs before building.

Terminal

# examples for common build.rs needs
apt-get update && apt-get install -y cmake clang libclang-dev protobuf-compiler

How to prevent it

Bake the build-time tools your -sys crates need into the runner image.
Read build.rs/crate docs for required system tooling before adding a dependency.
Use cargo build -vv to surface build-script commands when diagnosing.