rust-lang/cargo · error · anyhow::Error

"--package <SPEC>" requires a SPEC format value, which can b

Error message

"--package <SPEC>" requires a SPEC format value, which can be any package ID specifier in the dependency graph.
Run `cargo help pkgid` for more information about SPEC format.

What it means

In compile_options, after building CompileOptions, if no workspace is present but `--package` was passed with zero values (is_present_with_zero_values), Cargo bails because `-p`/`--package` requires a SPEC argument naming a package ID specifier in the dependency graph. As the comment notes, since cargo 0.50.0 clap normally prevents this, but the guard catches any path that sneaks through.

Source

Thrown at src/util/command_prelude.rs:861

                self._values_of("example"),
                self.flag("examples"),
                self._values_of("bench"),
                self.flag("benches"),
                self.flag("all-targets"),
            ),
            target_rustdoc_args: None,
            target_rustc_args: None,
            target_rustc_crate_types: None,
            rustdoc_document_private_items: false,
            honor_rust_version: self.honor_rust_version(),
        };

        if let Some(ws) = workspace {
            self.check_optional_opts(ws, &opts)?;
        } else if self.is_present_with_zero_values("package") {
            // As for cargo 0.50.0, this won't occur but if someone sneaks in
            // we can still provide this informative message for them.
            anyhow::bail!(
                "\"--package <SPEC>\" requires a SPEC format value, \
                which can be any package ID specifier in the dependency graph.\n\
                Run `cargo help pkgid` for more information about SPEC format."
            )
        }

        Ok(opts)
    }

    fn cli_features(&self) -> CargoResult<CliFeatures> {
        CliFeatures::from_command_line(
            &self._values_of("features"),
            self.flag("all-features"),
            !self.flag("no-default-features"),
        )
    }

    fn compile_options_for_single_package(

View on GitHub (pinned to 0e07a15537)

Solutions

1. Supply a package SPEC: `cargo build -p my-crate` (or `-p my-crate:0.1.0`).
2. If you want all workspace packages, use `--workspace` / `--all` instead of bare `-p`.
3. Inspect the command/script that builds the cargo invocation and ensure the `-p` value is not stripped by quoting/word-splitting.

Example fix

# before
cargo build -p

# after
cargo build -p my-crate

// If building the cargo ArgMatches programmatically, never mark `package`
// present without a value.
fn packages_arg(matches: &ArgMatches) -> Vec<String> {
    let v = matches._values_of("package");
    assert!(!v.is_empty(), "--package requires a SPEC value");
    v
}

if let Err(e) = cli.compile_options(...) {
    if e.to_string().contains("requires a SPEC format value") {
        eprintln!("usage: cargo build -p <SPEC>");
    }
    return Err(e);
}

When it happens

Trigger: Invoking a compile-like subcommand with `--package` (or `-p`) but no value, in a context where clap did not enforce the required value — e.g. calling the argument-parsing path programmatically with an empty package flag, or a shell alias that drops the value.

Common situations: A shell alias or script that runs `cargo build -p` and accidentally omits the package name; programmatic construction of ArgMatches that marks `package` present with zero values.

Related errors

• argument for --color must be auto, always, or never, but fou
• invalid character `+` in dependency name: `+{toolchain}`
• invalid character `+` in package name: `+{toolchain}` Us
• missing crate name before '@'
• --exclude can only be used together with --workspace

AI-assisted analysis of rust-lang/cargo@0e07a15537 (2026-08-06). Data as JSON: /data/errors/b4f4683b8d981fc3.json. Report an issue: GitHub.