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.
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
--- stderrblock - 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 -vvto see the full build-script command and output.
Install the build-time dependency
Provide the tool the script needs before building.
# examples for common build.rs needs
apt-get update && apt-get install -y cmake clang libclang-dev protobuf-compilerHow to prevent it
- Bake the build-time tools your
-syscrates need into the runner image. - Read
build.rs/crate docs for required system tooling before adding a dependency. - Use
cargo build -vvto surface build-script commands when diagnosing.