1. Symptoms
When the Rust compiler encounters error E0620, you will see output similar to the following in your terminal:
error[E0620]: unresolved import
--> src/main.rs:3:5
|
3 | use std::collections::HashMap;
| ^^^^^^^^^^^^^^^^^^^^^^^ unresolved import
|
= help: possible candidates are found in other crates, provide at least one additional import path like `use crate_name::collections::HashMap`
Alternatively, when referencing a module that doesn’t exist:
error[E0620]: unresolved import `foo::bar::baz`
--> src/lib.rs:5:12
|
5 | use foo::bar::baz::Quux;
| ^^^^^^^^^^^ unresolved import
The error manifests in several observable ways depending on the context. When you attempt to import a module that has not been declared in the nearest Cargo.toml or that doesn’t exist in the specified path, the compiler halts compilation and reports this specific error code. The error message explicitly states “unresolved import” and pinpoints the exact location in your source file where the problematic import statement resides.
In more complex scenarios involving nested modules, you might encounter variations where the import path partially resolves but fails at a deeper level. For instance, you might successfully import a parent module but then fail to access a child module that hasn’t been declared. The error will indicate precisely which segment of the import path could not be resolved, making it easier to identify whether the problem lies with module declaration, path construction, or external crate configuration.
When working with workspace configurations, E0620 can also appear when trying to import from a crate that hasn’t been added as a dependency in the workspace’s root Cargo.toml. The compiler provides helpful suggestions when possible, indicating if the module might exist in a different crate that requires explicit addition to your dependencies.
2. Root Cause
The E0620 error occurs when the Rust compiler cannot locate the module, struct, enum, function, or constant specified in a use statement. This fundamentally stems from mismatches between what your code expects to import and what actually exists in the specified location. Understanding the module system’s mechanics reveals several distinct scenarios that trigger this error.
First, the module might genuinely not exist at the specified path. Rust’s standard library follows a well-defined structure, and attempting to import from non-existent paths like std::nonexistent::Module immediately produces E0620. Similarly, third-party crates expose specific APIs through their documented module hierarchies, and importing from undocumented or removed paths will fail.
Second, the module might exist but not be re-exported through the crate’s public API. In Rust, modules are internal organizational units, and their contents are not automatically accessible to external crates unless explicitly marked as pub. If you attempt use crate_name::internal_module::HelperStruct, but internal_module is not declared pub in the crate’s root, the import fails even though the module technically exists within the crate’s source.
Third, the module might be conditional based on feature flags or platform-specific compilation. Many crates provide optional functionality gated behind feature flags in their Cargo.toml. If you attempt to import a type that only exists when a specific feature is enabled, but that feature isn’t active in your dependency declaration, E0620 results.
Fourth, typos in import paths remain a persistent source of E0620. Rust is case-sensitive, so use std::io::Bufreader will fail if you meant BufReader with the capital R. Similarly, pluralization differences (collections vs collection) and simple spelling errors prevent module resolution.
Fifth, when working with nested modules defined in separate files, E0620 appears if you declare a module with mod submodule; but fail to create the corresponding submodule.rs or submodule/mod.rs file. The module declaration tells the compiler to expect the module, but the missing file prevents resolution.
3. Step-by-Step Fix
Resolving E0620 requires identifying why the import path fails and correcting the mismatch. Follow these systematic steps to diagnose and fix the issue.
Step 1: Verify the Module Path in Documentation
Consult the crate’s documentation to confirm the correct import path. For standard library types, check the Rust API documentation at docs.rs. For external crates, review the crate’s README or generated documentation on crates.io.
Before:
use std::collections::HashMap; // This is correct
use std::collection::HashMap; // Wrong: 'collection' should be plural
After:
use std::collections::HashMap;
Step 2: Check Module Visibility
Ensure the module or item you’re importing is declared as pub. If you’re importing from an external crate, the item must be part of the crate’s public API.
Before:
// In some_library crate
mod internal {
pub struct Helper; // Module is private!
}
After:
// In some_library crate
pub mod internal {
pub struct Helper;
}
Step 3: Enable Required Features
If importing from a crate that requires feature flags, add the appropriate features to your Cargo.toml.
Before:
[dependencies]
serde = "1.0"
use serde::ser::SerializeStruct;
After:
[dependencies]
serde = { version = "1.0", features = ["derive"] }
Step 4: Declare Missing Modules
If defining your own modules, ensure the module file exists and is properly declared.
Before:
// src/lib.rs
mod utils; // Compiler expects src/utils.rs or src/utils/mod.rs
After:
Create the file src/utils.rs:
pub fn helper() {
println!("Helper function");
}
Step 5: Add External Crate Dependencies
If importing from a crate not already in your project, add it to Cargo.toml.
Before:
use rand::Rng;
After:
[dependencies]
rand = "0.8"
4. Verification
After applying the fix, verify that the error has been resolved by recompiling your project. Run the following command to check for any remaining errors:
cargo build
If the fix was successful, the output should show no E0620 errors. For library projects, use cargo check instead, which performs faster compilation without producing binaries:
cargo check
Run your test suite to ensure the imported functionality works correctly:
cargo test
For projects with multiple targets, specify the package if needed:
cargo build --package my_package
If you previously had multiple E0620 errors (for example, cascading failures because one missing import prevented type inference for subsequent code), ensure all related code compiles by checking for any remaining errors. The compiler often reports multiple errors that share a common root cause; fixing the primary import issue may resolve several apparent problems simultaneously.
5. Common Pitfalls
Several recurring mistakes lead to E0620 errors, and recognizing them prevents wasted debugging time.
The first pitfall involves confusing use statements with file paths. Beginners often write use "module.rs" expecting automatic inclusion, but Rust requires explicit module declaration with mod. The mod keyword establishes the module’s existence, while use makes items accessible within the current scope.
The second pitfall concerns feature flag blindness. Many crates provide rich functionality through optional features that aren’t enabled by default. When importing types from features you haven’t activated, the compiler reports E0620 rather than suggesting the missing feature. Always read the crate’s Cargo.toml to understand which features provide the functionality you need.
The third pitfall involves case sensitivity in import paths. Rust preserves case exactly as written, and use std::fmt differs from use std::Fmt. This is particularly treacherous with acronyms, where use std::io::Utf8 might be attempted instead of use std::io::Utf8Error, or use std::fs::Path instead of use std::path::Path. The standard library uses specific casing conventions that must be matched precisely.
The fourth pitfall occurs when assuming module re-exports. The prelude pattern in Rust re-exports commonly used types for convenience, but this can create confusion about where types actually originate. If a type works in one context but not another, check whether you’re relying on prelude imports that aren’t universally available.
The fifth pitfall involves forgetting to run cargo update after adding new dependencies. Cargo caches registry information, and newly published crate versions won’t be fetched until you update. If you added a dependency but immediately encountered E0620, running cargo update might fetch a version with the module you need.
6. Related Errors
E0432 (Unresolved Import) shares significant overlap with E0620 and often appears in similar contexts. The distinction lies primarily in compiler evolution; E0432 was the original error code for this condition, and E0620 serves as a more specific identifier in newer Rust editions. Both errors indicate identical problems with import resolution, and the fix strategies are identical.
E0433 (Failed to Resolve) represents a broader category of resolution failures that encompasses not just imports but also macro invocations, trait bounds, and other name resolution contexts. While E0620 specifically targets import statements, E0433 catches resolution failures elsewhere in your code. The interplay between these errors often appears when a missing import causes downstream type inference failures that manifest as E0433.
E0580 (Main Function Not Found) relates to E0620 in the context of project structure errors. If your module declarations reference non-existent files, the compiler cannot find your main function because the crate structure is invalid. Resolving E0620 errors in module declarations often simultaneously resolves E0580 by allowing the compiler to properly parse the crate’s structure and locate the entry point.