rust-lang/cargo · error

"--package " requires a SPEC format value, which can be any…

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

When no Workspace is bound and the `--package` / `-p` flag is present with a zero/empty value, Cargo cannot resolve a SPEC and bails with guidance to consult `cargo help pkgid`. The guard covers a degenerate CLI state that newer clap prevents but older callers could still hit.

Solutions

1. Pass a concrete package name or SPEC: `cargo build -p my-crate`.
2. Fix the shell to guard against empty variables: `${PKG:?--package value required}`.
3. Run from inside the workspace so workspace-based resolution applies instead of the zero-value branch.

Example fix

# before
# cargo build -p "$PKG"   # PKG unset -> empty value

# after
# PKG="${PKG:?missing package name}"
# cargo build -p "$PKG"

fn require_package_spec(pkg: Option<&str>) -> Result<&str, String> {
    match pkg {
        Some(s) if !s.is_empty() => Ok(s),
        _ => Err("--package requires a non-empty SPEC; see `cargo help pkgid`".into()),
    }
}

// before building the cargo invocation:
// let spec = require_package_spec(pkg_opt)?;

fn is_non_empty_spec(s: Option<&str>) -> bool {
    matches!(s, Some(v) if !v.is_empty())
}

When it happens

Trigger: Invoking a subcommand with `--package` passed an empty string or no positional value, in a code path where workspace is None (is_present_with_zero_values("package") is true).

Common situations: Shell script interpolating an unset variable: `cargo build -p "$PKG"` with PKG empty; a wrapper tool forwarding a malformed argv; a clap value_parser regression letting empty through.

Related errors

• glob patterns on package selection are not supported.
• argument for --color must be auto, always, or never, but…
• argument for --color must be auto, always, or never, but…
• manifest path ` ` does not exist
• manifest path ` ` is a directory but expected a file

AI-assisted analysis of rust-lang/cargo@98a09e7e7d (2026-08-11). Data as JSON: /api/errors/b4f4683b8d981fc3. Report an issue: GitHub.

Appendix: source

Thrown at src/util/command_prelude.rs:865

                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 98a09e7e7d)