The compiler can't find the library file
You copy a snippet from a tutorial. It uses serde to serialize a struct. You paste the code into your main.rs. You hit run. The compiler screams error[E0463]: can't find crate for 'serde'. You check your code. The use serde::Serialize; line is there. The syntax is perfect. The compiler is right: it has no idea where serde lives.
This isn't a syntax error. The code is written correctly. This is a dependency resolution error. Cargo hasn't told the compiler where to find the library. E0463 means the compiler searched its known paths and found no file matching the crate name. The build stops because the compiler cannot proceed without the library.
Rust separates compilation from dependencies
Rust's toolchain splits work between two tools. rustc is the compiler. It turns Rust source code into machine code. Cargo is the build system. It manages dependencies, runs tests, and invokes rustc.
rustc does not know about the internet. It does not know about crates.io. It does not read Cargo.toml. rustc only knows about files on your disk. When you write use serde, rustc looks for a compiled library file named libserde.rlib (or a similar variant) in its search paths. If it can't find that file, it emits E0463.
Think of rustc as a chef who only cooks with ingredients sitting on the counter. Cargo is the sous-chef who runs to the store, buys the ingredients, and puts them on the counter. If the sous-chef hasn't run to the store yet, or put the ingredient in the wrong drawer, the chef throws a tantrum. E0463 is the chef saying, "I don't see the salt."
Cargo is the bridge. If the bridge is down, the compiler starves.
Minimal example: missing dependency
The most common cause of E0463 is a missing entry in Cargo.toml. You wrote code that uses a crate, but you never told Cargo to download it.
// main.rs
use serde::Serialize; // error[E0463]: can't find crate for 'serde'
#[derive(Serialize)]
struct Config {
port: u16,
}
fn main() {
let config = Config { port: 8080 };
println!("{:?}", config);
}
The compiler rejects this immediately. It sees use serde and searches for the crate. It finds nothing. The error points to the use line, but the fix is in Cargo.toml.
Add the dependency to the manifest. Run cargo build. Cargo reads the file, downloads serde, compiles it, and passes the location to rustc. The error disappears.
# Cargo.toml
[dependencies]
serde = "1.0"
Convention aside: serde = "1.0" is shorthand for >=1.0.0, <2.0.0. Cargo resolves this to the latest compatible version. If you want to add a dependency from the command line, use cargo add serde. This updates Cargo.toml for you and fetches the crate in one step.
How Cargo resolves crates
When you run cargo build, Cargo performs a sequence of steps. Understanding this sequence helps you debug E0463 when the obvious fix doesn't work.
- Cargo reads
Cargo.tomland builds a dependency graph. - Cargo checks the local registry in
.cargo/registry. If the crate is missing or outdated, Cargo downloads it from crates.io. - Cargo compiles the crate and its dependencies. The compiled artifacts land in
target/debug/deps. - Cargo invokes
rustcwith flags that include-L dependency=target/debug/deps. This flag tellsrustcto search that directory for library files. rustcparses your code. When it hitsuse serde, it looks in the-Ldirectory, findslibserde.rlib, and links it.
If any step fails, E0463 can appear. If Cargo.toml is missing the entry, step 1 skips the crate. Step 4 never passes the -L flag for that crate. rustc looks and finds nothing.
If the network is down, step 2 fails. You get a network error, not E0463. E0463 is strictly about missing files on disk. If you see E0463, the network is not the problem. The file is simply not where the compiler expects it.
Check the package name. Cargo maps names, and a mismatch breaks the link.
Realistic scenario: local workspaces and path dependencies
You build a library in a sibling folder. You want to use it in your binary. You add a path dependency.
# Cargo.toml of the binary
[dependencies]
my_lib = { path = "../my_lib" }
This works if the path is correct and the library compiles. E0463 appears if the path points to a non-existent directory, or if the library fails to compile. If the library fails to compile, Cargo stops before invoking rustc for the binary. You see the library's error first.
A subtler case involves package names. Cargo uses the package name from Cargo.toml as the crate name by default. If my_lib/Cargo.toml has name = "my-library", the crate name is my-library. You must depend on my-library, not my_lib.
# Correct dependency key matches the package name
[dependencies]
my-library = { path = "../my_lib" }
If you use the wrong key, Cargo might treat it as a separate crate or fail to resolve the path. The result is E0463. Check the name field in the dependency's Cargo.toml. The key in your dependency list must match that name.
Pitfalls and edge cases
E0463 has a few specific triggers beyond missing dependencies.
Typos in crate names.
If you write use serd::Serialize;, the compiler looks for a crate named serd. It doesn't find it. You get E0463 for 'serd'. Check the spelling. The error message shows the exact crate name the compiler is searching for.
mdbook and isolated compilation.
If you are writing a book with mdbook and running mdbook test, the examples are compiled with rustc directly, not through Cargo. mdbook ignores Cargo.toml. It compiles snippets in isolation to ensure they are self-contained.
If your examples depend on crates, mdbook cannot find them. You must pass the library path manually.
# Build the library first so the .rlib exists
cargo build -p my_lib
# Pass the path to mdbook so rustc can find the crate
mdbook test --library-path target/debug/deps
Without --library-path, mdbook test emits E0463 for every external crate. This is a common trap for book authors. The fix is to build the dependencies and point mdbook at the output.
Broken toolchain.
If E0463 appears for standard library crates like std or core, your Rust installation is broken. rustc should always find std in the sysroot. If it can't, the toolchain files are missing or corrupted.
Run rustup show to check the active toolchain. Look for the sysroot path. If the path is missing or points to an empty directory, reinstall the toolchain.
rustup default stable
rustup update stable
This repairs the installation. E0463 for std is rare. It usually indicates a manual tampering with the Rust installation or a disk failure.
cargo clean as a reset.
Sometimes the dependency graph gets stuck. Cargo might cache a bad state. Running cargo clean deletes the target directory. The next build starts from scratch. This forces Cargo to re-resolve dependencies and re-compile everything. It's the nuclear option, but it clears stale artifacts that can cause phantom errors.
Trust the error. E0463 means the file is missing. Find the file or tell Cargo where it is.
Decision: when to use which approach
Use cargo add <crate> when you want Cargo to fetch the latest compatible version and update Cargo.toml for you. This is the fastest way to add a dependency from crates.io.
Use manual Cargo.toml editing when you need precise control over version constraints, features, or source registries. This gives you full visibility into the manifest.
Use path dependencies when you are developing a local library and need to test changes instantly without publishing. This links your binary to the local code.
Use --library-path with mdbook test when your book examples depend on crates that mdbook cannot resolve via Cargo.toml. This bridges the gap between isolated compilation and external libraries.
Use rustup show when E0463 appears for standard library crates like std or core, indicating a broken toolchain installation. This diagnoses sysroot issues.
Pick the tool that matches your workflow. Don't fight Cargo; configure it.