1. Symptoms
When the Rust compiler encounters error E0562, you will see a diagnostic message similar to the following in your build output:
error[E0562]: extern crate cannot be imported as non-default module name
--> src/main.rs:3:1
|
3 | extern crate serde as match;
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= help: the crate `serde` cannot be imported as non-default module name `match`
The error indicates that the identifier you attempted to use after the as keyword is not a valid Rust module name. This typically manifests when you try to rename an external crate to a reserved keyword, a name beginning with a numeric digit, or an identifier containing invalid characters for Rust modules.
Additional symptoms may include compilation failure that prevents the binary or library from being built. The error is detected at the parsing stage, so you may not see any other errors until this one is resolved. The compiler will also provide helpful guidance about which specific identifier caused the problem and why it is invalid.
2. Root Cause
The root cause of error E0562 lies in Rust’s module naming rules, which are stricter than the allowed characters in crate names from crates.io or other sources. When you write extern crate some_crate as new_name;, the identifier after as must conform to Rust’s identifier syntax rules defined in the language reference.
Rust identifiers cannot be reserved keywords such as match, if, loop, fn, struct, enum, impl, trait, pub, mod, use, const, static, let, mut, ref, return, break, continue, for, while, in, as, where, type, async, await, dyn, unsafe, move, and several dozen others. These words have special meaning in the Rust grammar and cannot be repurposed as module names, even when used as renamed imports.
Additionally, identifiers must begin with a Unicode alphabetic character or an underscore, not a digit. They cannot contain whitespace, hyphens, at-signs, dollar signs, percent signs, or other punctuation characters that are valid in crate names. The module namespace in Rust follows the same lexical rules as variable and function names.
This error frequently occurs when developers attempt to rename a crate to a short convenience name that happens to collide with a keyword, or when importing crates that have names containing characters incompatible with Rust identifiers. The compiler enforces this constraint because modules become part of the namespace hierarchy and must obey identifier syntax.
3. Step-by-Step Fix
To resolve error E0562, you must choose a valid identifier for the renamed import. The solution involves replacing the invalid name with a permissible identifier that does not conflict with reserved keywords or violate naming rules.
Before:
extern crate serde as match;
After:
extern crate serde as ser;
Before:
extern crate rocket as 4rockets;
After:
extern crate rocket as rocket_lib;
Before:
extern crate cross-beam as cross beam;
After:
extern crate cross_beam as cross_beam;
The general fix process follows these steps:
First, identify the invalid identifier in the extern crate statement that triggered the error. The compiler message will point directly to the problematic line.
Second, select an alternative name that satisfies these criteria: it must not be a Rust keyword, must begin with a Unicode letter or underscore, and may only contain Unicode letters, digits, and underscores thereafter. If you need multiple words, use underscores to separate them as is conventional in Rust.
Third, replace the invalid identifier in your code with the chosen valid name. Ensure that all subsequent references to the module in your code use the corrected name to avoid secondary errors.
Fourth, verify that the new name does not conflict with any existing modules, imports, or items in the relevant scope where you will be using it.
4. Verification
After applying the fix, rebuild your project to confirm that error E0562 no longer appears. Run your standard build command:
cargo build
A successful verification will show the compilation completing without error E0562. The output should indicate that the binary or library compiled successfully, or proceed to report other unrelated errors if your code has additional issues.
You should also verify that the renamed module functions correctly in your code. Check that all usages of the old invalid name have been replaced with the new valid identifier, or that any use statements importing items from the renamed crate reference the corrected module path.
Testing the functionality that depends on the external crate ensures that the rename did not introduce logical errors. If your code previously referenced items through the renamed crate and those references were working before, they should continue to work after fixing the naming issue provided the new identifier is used consistently.
For projects using edition 2018 or later, consider whether the extern crate statement is necessary at all. The 2018 edition introduced direct crate imports without requiring explicit extern crate declarations, which can eliminate these naming concerns entirely for many use cases:
// Edition 2018 and later - extern crate is often unnecessary
use serde::{Deserialize, Serialize};
5. Common Pitfalls
One common pitfall is assuming that any name valid in other programming languages will work in Rust. Keywords like match, in, and where are reserved in Rust but may be valid identifiers in languages like Python, JavaScript, or Go. Always consult the list of Rust keywords when choosing a rename identifier.
Another pitfall is using crate names directly without renaming when the crate name happens to contain hyphens, which are converted to underscores automatically. While extern crate my-crate; works, the generated module name will be my_crate, not my-crate. Attempting to rename to a hyphenated name like extern crate my-crate as my-crate; will trigger E0562.
Developers sometimes forget that renaming a crate affects all code that references it. After fixing the extern crate statement, you must update every use statement and path that references the old invalid name. Missing updates will produce E0433 errors about unresolved imports.
When working in a team environment, ensure that all developers use the same renamed identifier for consistency. Document the chosen name in your project’s README or contributing guidelines if you deviate from the crate’s default name.
Finally, avoid overly short names like single letters or abbreviations that could create confusion. While s or x are technically valid identifiers, they make code harder to read and maintain. Choose descriptive names that indicate the crate’s purpose while remaining concise.
6. Related Errors
E0254: An import was not found in the crate’s root. This error occurs when attempting to import an item that does not exist in the target crate or module. It often accompanies E0562 when fixing rename issues if the new module name does not properly align with the crate’s exported items.
E0433: Failed to parse rlib. This error may appear when an external crate cannot be found or loaded correctly. While different from E0562 in cause, it can occur in the same codebase if the crate name in the extern crate statement is misspelled or the dependency is missing from Cargo.toml.
E0463:่น found a rlib which is not a target This error indicates that the compiler found a crate but it was not compiled as the expected target type. It relates to E0562 in that both involve external crate loading, though E0562 specifically concerns naming validity rather than target architecture compatibility.