Cargo — build script failed with a confusing exit status

Debug Cargo build script failures by reading build output and reproducing the underlying command.

intermediatedebuggingrustcargo

Symptoms

error: failed to run custom build command for crate
build script failed with exit status
A native dependency is not found during the build
The error only appears on a fresh build or in CI

Possible causes

A required system library or tool is missing
The build script cannot find an environment variable or path
A pkg-config probe fails because the library is not installed
The build script panics or emits an unclear error

Diagnosis steps

Read the full build script output

cargo build -vv 2>&1 | grep -A20 "build command"

Interpretation

Verbose output shows the script stdout and stderr, which usually names the missing library or variable.

Reproduce the underlying command

pkg-config --cflags --libs openssl

Interpretation

Running the probe the build script uses confirms whether the system dependency is discoverable.

Install or point at the dependency

export OPENSSL_DIR=/usr/local/opt/openssl

Interpretation

Setting the variable the build script looks for resolves lookups that fail due to non-standard install paths.

Root cause

The build script could not complete because a system dependency, tool or environment variable it depends on was missing or not discoverable in the build environment.

Fix

Install the missing system library or tool, set the environment variables the build script expects, and ensure the build environment has the same dependencies as the development machine.

Verify the fix

Rebuild and confirm the script completes, and confirm the crate links and runs against the native dependency it detected.

Symptom walkthrough

The build fails with failed to run custom build command for a crate, followed by a build script error or an exit status that hides the real message. Build scripts compile and probe native dependencies, so the failure is usually a missing system library, an absent tool such as pkg-config, or an environment variable the script needs. It is common on fresh CI images that lack development headers.

Fix in practice

Run the build verbosely to see the script output, then install the missing system dependency or tool and set the environment variables the script looks for. Reproducing the exact probe command outside Cargo confirms the diagnosis and the cure.

Verification

Rebuild and confirm the script completes, then run the crate and confirm it links against the native library it detected. A successful link and run proves the environment now satisfies the script.

Diagnostic commands

Check the behavior with commands like these:

cargo build -vv 2>&1 | grep -A20 "build command"
pkg-config --cflags --libs openssl
export OPENSSL_DIR=/usr/local/opt/openssl