rust-lang/cargo · error
{err}{help}
Error message
{err}{help} What it means
`check_name` runs the package name through `PackageName::new`, which enforces crate-name rules (lowercase ASCII, no leading/trailing hyphens, no double hyphens, non-empty, etc.). On failure it appends contextual help (`bin_help`) explaining how to keep a binary with a different name via `[[bin]] name = ...` / `src/bin/<name>.rs`. The `{err}` is the underlying PackageName validation message; `{help}` is the appended guidance.
Solutions
- Use an explicit valid name: `cargo new --name my-project my-project` (lowercase ASCII, hyphens/underscores only, no leading/trailing hyphen).
- Rename/recreate the target directory with a valid package name (lowercase, no spaces).
- Follow the appended help: keep a valid package name and set the binary name separately with `[[bin]] name = "Desired" path = "src/main.rs"` or via `src/bin/Desired.rs`.
Example fix
# before $ cargo new "My Project" # error: invalid name (uppercase + space) # after $ cargo new --name my-project "My Project" # or $ cargo new my-project
Defensive patterns
Strategy: validation
Validate before calling
// Mirror cargo's PackageName rules before invoking `cargo new --name`.
fn valid_package_name(name: &str) -> bool {
!name.is_empty()
&& name.chars().all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-' || c == '_')
&& !name.starts_with('-') && !name.ends_with('-')
&& !name.contains("--")
} Type guard
fn is_valid_package_name(name: &str) -> bool { valid_package_name(name) } Prevention
- Pre-validate names: lowercase ASCII, hyphens/underscores only, no leading/trailing/double hyphens.
- Derive package names from directory names with a sanitizer that lowercases and replaces invalid chars.
- When scaffolding from CamelCase folders, always pass an explicit `--name` with a cleaned value.
- Run a quick `PackageName::new(name)`-equivalent check in your generator before shelling out.
When it happens
Trigger: `cargo new`/`cargo init` deriving a name from a directory that contains uppercase letters, spaces, or invalid characters (e.g. `cargo new My-Project` where the dir yields an invalid name), or passing `--name` with such a value. `PackageName::new("Foo Bar")`, `PackageName::new("-foo")`, `PackageName::new("foo--bar")`.
Common situations: Directory names with capitals or spaces (e.g. creating from a `CamelCase` folder). Accidental leading hyphen in `--name`. Names with dots or special punctuation. Renaming a directory to something non-snake/kebab before `cargo init`.
Related errors
- invalid package name
- invalid package name
- invalid package name `test`: it conflicts with Rust's…
- invalid package name
- can't specify both lib and binary outputs
AI-assisted analysis of rust-lang/cargo@98a09e7e7d (2026-08-11).
Data as JSON: /api/errors/6b9c7b0d9f10091f.
Report an issue: GitHub.
Appendix: source
Thrown at src/ops/cargo_new.rs:155
help.push_str(&format!(
"\n\
help: to name the binary \"{name}\", use a valid package \
name, and set the binary name to be different from the package. \
This can be done by setting the binary filename to `src/bin/{name}.rs` \
or change the name in Cargo.toml with:\n\
\n \
[[bin]]\n \
name = \"{name}\"\n \
path = \"src/main.rs\"\n\
",
name = name
));
}
help
};
PackageName::new(name).map_err(|err| {
let help = bin_help();
anyhow::anyhow!("{err}{help}")
})?;
if restricted_names::is_keyword(name) {
anyhow::bail!(
"invalid package name `{}`: it is a Rust keyword{}",
name,
bin_help()
);
}
if restricted_names::is_conflicting_artifact_name(name) {
if has_bin {
anyhow::bail!(
"invalid package name `{}`: \
it conflicts with cargo's build directory names{}",
name,
name_help
);
} else {View on GitHub (pinned to 98a09e7e7d)