Troubleshooting
If cargo-cgp, the check command for Context-Generic Programming projects, will not
start or behaves unexpectedly, begin with the symptom index below. For a tool that runs but reports
an unfamiliar CGP error, Reading the output explains the diagnostic instead.
Many startup failures involve a mismatch between the front end, cargo-cgp-driver, and the pinned
nightly. The front end normally finds the driver beside itself, and the driver loads that nightly's
compiler libraries. The paths and loader messages here are from Linux, the platform on which the
tool has been tested.
Start with the symptom index
Find the distinctive part of your error in the left column, then read the section it points to.
| Error fragment | Cause | Section |
|---|---|---|
toolchain … is not available | the pinned nightly is not installed | The preflight rejects the setup |
could not run under toolchain | the driver was built against another nightly | The preflight rejects the setup |
out of lockstep | the front end and driver have different versions | The preflight rejects the setup |
was built against | the pinned nightly changed since the driver was built | The preflight rejects the setup |
could not parse the … --version output | an old or unrelated driver binary | The preflight rejects the setup |
rustup was not found on PATH | no rustup for the preflight or setup | The preflight rejects the setup, Setup fails |
error while loading shared libraries: librustc_driver-… | library path unset, or the wrong toolchain | The driver cannot load the compiler |
failed to run the cargo-cgp-driver | driver missing | The driver cannot be found |
could not execute process … (never executed) | driver path wrong, with the preflight turned off | The driver cannot be found |
no such command: `frobnicate` with the four commands listed | wrong command name | The command itself fails |
no such command: `cgp` | the tool is not installed, or not on PATH | The command itself fails |
could not find Cargo.toml | run outside a cargo package | The command itself fails |
unexpected argument | a flag cargo check does not know | The command itself fails |
is cargo on PATH? | cargo is not installed, or not on PATH | The command itself fails |
RUSTC_WORKSPACE_WRAPPER is set | a compiler wrapper of your own will not run | Your own compiler wrapper stopped running |
| no error: a check never finishes, or its errors change between runs | a bug under the compiler's parallel front end | A check hangs or prints different output between runs |
Some problems print no error at all: a check that disagrees with cargo check, and a slow first check.
Each has a section near the end of the page.
Narrowing it down
When the index does not identify the problem, rerun the check and look at its first message.
Before checking code, the front end performs a read-only test of the toolchain and driver, called
the preflight. A message ending in help: run `cargo cgp setup` comes from that test;
the preflight section explains its possible results.
If the preflight passes, run the check verbosely:
cargo cgp check -v
Once cargo begins compiling crates, the verbose output includes Running lines invoking
cargo-cgp-driver … rustc …. A failure before those invocations points to the front end or setup.
A failure from an invocation points to the driver or compiler.
The preflight rejects the setup
Most failures below can be repaired with cargo cgp setup, which installs the pinned nightly
and builds a driver matching both that compiler and the front end. Before rerunning setup,
read the diagnostic to identify which part failed.
The examples name nightly-2026-11-16; your output names your build's pinned nightly. Driver
messages also show the binary's path and where it was found: through CARGO_CGP_DRIVER, beside
the front end, or on PATH.
The preflight begins by checking for the pinned nightly. If rustup cannot find it, the message includes rustup's explanation:
error: toolchain `nightly-2026-11-16` is not available:
error: toolchain 'nightly-2026-11-16-x86_64-unknown-linux-gnu' is not installed
help: run `rustup toolchain install nightly-2026-11-16-x86_64-unknown-linux-gnu` to install it
help: run `cargo cgp setup`
The front end finds the pinned nightly through rustup, so a machine without rustup gets a different message.
Here setup cannot help, since it needs rustup too:
error: rustup was not found on PATH, and cargo-cgp installs and selects its toolchain `nightly-2026-11-16` through rustup
help: install rustup, or install cargo-cgp through its Nix flake, which needs no rustup
The Nix flake runs the front end without the preflight.
Once the nightly is available, the preflight tries to run the driver under it. Failure at this point usually means the driver was built against another nightly. The diagnostic includes the loader's message so you can see which library could not be loaded:
error: the cargo-cgp-driver at /home/you/.cargo/bin/cargo-cgp-driver (beside cargo-cgp) could not run under toolchain `nightly-2026-11-16` (it was likely built against a different nightly):
/home/you/.cargo/bin/cargo-cgp-driver: error while loading shared libraries: librustc_driver-a1ed262f84b24882.so: cannot open shared object file: No such file or directory
help: run `cargo cgp setup`
Starting successfully establishes that the driver can load, but not that it matches the front end. A partial upgrade or an older binary found first can leave their versions out of agreement:
error: the cargo-cgp-driver at /home/you/.cargo/bin/cargo-cgp-driver (beside cargo-cgp) is version 0.0.9, but this cargo-cgp is 0.1.0 (the two are out of lockstep)
help: run `cargo cgp setup`
Matching version numbers are not sufficient if the compiler has changed since the driver was built. The preflight compares the build-time compiler with the one the pinned toolchain now provides and reports a mismatch:
error: the cargo-cgp-driver at /home/you/.cargo/bin/cargo-cgp-driver (beside cargo-cgp) was built against `rustc 1.99.0-nightly (0000000 2026-01-01)`, but toolchain `nightly-2026-11-16` provides `rustc 1.102.0-nightly (5f4effd57 2026-11-13)`
help: run `cargo cgp setup`
The version query can also reveal that the file found as the driver is an unrelated program, or otherwise does not return the expected version information:
error: could not parse the `--version` output of the cargo-cgp-driver at /home/you/.cargo/bin/cargo-cgp-driver (beside cargo-cgp)
help: run `cargo cgp setup`
For a build from a source checkout, CARGO_CGP_NO_MANAGE=1 lets you bypass the installed-setup
preflight. You must then supply the matching toolchain yourself. If that environment is wrong,
the failure usually comes from library loading, as described below.
The driver cannot load the compiler
This failure comes from the operating system's loader, before the driver's own code runs, which is why it looks unlike any other message from the tool:
cargo-cgp-driver: error while loading shared libraries: librustc_driver-a1ed262f84b24882.so: cannot open shared object file: No such file or directory
The driver needs the exact librustc_driver-<hash>.so it linked against when built. Your hash may
differ from the example, but the failure means the loader could not find that specific library.
The remedy depends on how the driver was started.
If you invoked cargo-cgp-driver directly, its environment may lack the library path that the
front end normally supplies. Even a working installation can fail this way. Retry with the
pinned nightly's lib directory on the path:
LD_LIBRARY_PATH="$(rustc +nightly-YYYY-MM-DD --print sysroot)/lib" cargo-cgp-driver --version
Put the pinned nightly in place of nightly-YYYY-MM-DD. A driver installed with Nix has the path built in and
does not need this.
During a check, the same missing-library error can mean the active toolchain differs from the one the driver needs. Disabling the preflight also disables automatic nightly selection, so cargo may try to start the driver under another toolchain:
error: process didn't exit successfully: `…/cargo-cgp-driver …/stable-…/bin/rustc -vV` (exit status: 127)
--- stderr
…/cargo-cgp-driver: error while loading shared libraries: librustc_driver-a1ed262f84b24882.so: cannot open shared object file: No such file or directory
In that case, unset CARGO_CGP_NO_MANAGE so the tool switches to the pinned nightly itself, or make that nightly
the active toolchain, for example with RUSTUP_TOOLCHAIN. Running through the Nix flake also handles it.
The driver cannot be found
An explicit CARGO_CGP_DRIVER selects the driver path. Otherwise, the front end first looks
beside itself and then falls back to PATH. If no driver is available, the preflight reports:
error: failed to run the cargo-cgp-driver (none is beside cargo-cgp or on PATH): No such file or directory (os error 2)
help: run `cargo cgp setup`
With the preflight turned off by CARGO_CGP_NO_MANAGE, the missing driver reaches cargo instead, which reports a
compiler wrapper it could not start:
error: could not execute process `/path/to/cargo-cgp-driver …/stable-…/bin/rustc -vV` (never executed)
Caused by:
No such file or directory (os error 2)
Restore a reachable driver by running cargo cgp setup, selecting the actual binary through
CARGO_CGP_DRIVER (such as target/debug/cargo-cgp-driver in a checkout), or using the Nix flake
that installs both programs together. Keeping the installed binaries side by side avoids the
fallback to a possibly older driver on PATH.
The command itself fails
Some failures happen before the driver is involved. An unknown command is reported with the list the tool accepts:
error: no such command: `frobnicate`
help: the commands are `check`, `expand`, `setup`, and `update`
An unknown cgp command comes from cargo itself: it could not find cargo-cgp on PATH.
Check that the tool is installed and visible in the shell where you invoked cargo:
error: no such command: `cgp`
Running outside a cargo package also produces cargo's error rather than the tool's, because the tool runs
cargo check:
error: could not find `Cargo.toml` in `/some/dir` or any parent directory
Similarly, cargo rejects a flag cargo check does not know, since every argument after check is passed to it:
error: unexpected argument '--nope' found
If cargo itself is not on PATH, the front end reports that when it tries to run the check:
error: failed to run `cargo check` (is cargo on PATH?)
Caused by:
No such file or directory (os error 2)
Setup fails
cargo cgp setup installs the toolchain through rustup, so without rustup it stops at once:
Installing toolchain `nightly-2026-11-16` with rustc-dev and llvm-tools
error: rustup was not found on PATH, and `cargo cgp setup` installs the toolchain `nightly-2026-11-16` through rustup
help: install rustup, or install cargo-cgp through its Nix flake, which needs no rustup
You can resolve the missing rustup by installing it first or choosing the Nix flake. Once rustup is available, setup still needs a network connection for the toolchain and driver source downloads. Errors during those steps come from rustup or cargo, whose messages identify the failure.
The check disagrees with cargo check
When the checks disagree, trust your own toolchain's cargo check to decide whether the code
compiles. The tool uses a pinned nightly and the next-generation trait solver, so code relying on
nightly-only or solver-specific behavior can produce a different result. Mutually inheriting
namespaces, for example, pass the tool's check but are rejected by stable Rust. Use the tool to
understand CGP failures while retaining the ordinary check as the build authority.
The first check is slow
A check uses its own toolchain and build artifacts, so its first run recompiles the project's
dependencies into target/cgp within the project target directory. Subsequent runs reuse that
build wherever inside the project you invoke them.
Your own compiler wrapper stopped running
To rewrite workspace diagnostics, the tool assigns its driver to RUSTC_WORKSPACE_WRAPPER for
this run. Any wrapper you selected through that variable is therefore replaced, and the tool
prints a warning. Normal builds keep your original setting:
warning: RUSTC_WORKSPACE_WRAPPER is set to `/usr/local/bin/my-wrapper`; cargo-cgp replaces it with its driver for this run, so that wrapper does not run
A wrapper given through RUSTC_WRAPPER, such as sccache, does keep running alongside the driver.
A check hangs or prints different output between runs
The pinned nightly checks your code on several threads by default. The Rust project calls this the parallel front end and explains it in Enabling the parallel frontend on nightly. A check is meant to print the same output on every run, however many threads the compiler uses, so a check that never finishes, or that prints different errors from one run to the next, may have met a bug in that parallel code. You can rule it out by running the check on one thread:
RUSTFLAGS="-Zunstable-options --jobs-frontend=1" cargo cgp check
The tool passes these flags to the compiler unchanged. Set them in the environment, as here, rather
than in your project's .cargo/config.toml: a setting there also reaches your ordinary builds, and
stable Rust rejects -Z flags. Because cargo rebuilds whenever RUSTFLAGS changes, the first check
with the flags recompiles your dependencies, and later checks reuse that build.
One difference is expected, so look for it before reporting anything. The compiler can describe a cycle error from a different starting point on each run, and a check keeps that error as the compiler wrote it.
If the problem goes away on one thread, the next question is whether the compiler has it too.
Run plain cargo +nightly-YYYY-MM-DD check without the flags, using the pinned nightly that the
driver's --version names, run as shown above. If that check also
hangs or crashes, the bug is in the compiler, and the blog post says where to report it. If it does
not, please report the problem on the
issue tracker with the output of both runs of
cargo cgp check. A plain check that lists its errors in a different order on each run is no sign
of a bug: the post describes that as expected under the parallel front end.
Still stuck
If the failure suggests a mismatch but does not fit one section exactly, restoring the matching
nightly and driver is a useful next step. On the cargo path, run cargo cgp setup; on the Nix
path, reinstall the profile.
Failures not covered here are worth reporting on the
issue tracker. Include the output of cargo cgp check -v,
cargo cgp --version, and the driver's --version run as shown
above.
An AI agent wrote this page using the CGP knowledge base, and its messages were produced by running the tool. See How AI is used in this project.