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

extra arguments to ` ` can only be passed to one target…

Error message

extra arguments to `{}` can only be passed to one target, consider filtering
the package by passing, e.g., `--lib` or `--bin NAME` to specify a single target

What it means

Thrown when extra rustc or rustdoc args (from -- target args) are supplied but the build resolved to a number of root units other than one. Extra args can only attach to a single target, so cargo refuses to guess which unit receives them.

Solutions

Add a target filter to select exactly one unit, as the message suggests: `--lib`, `--bin NAME`, `--example NAME`, etc.
Narrow the package too if needed: `-p <pkg> --lib`.
Avoid trailing `-- <args>` unless you have already constrained to a single target.

Example fix

# before
cargo build -- --cfg foo
# after
cargo build --bin myapp -- --cfg foo

Defensive patterns

Strategy: validation

Validate before calling

// Count selected root units before forwarding `--` args.
// Heuristic: require exactly one of --lib/--bin NAME/--example NAME/--test NAME
// when the command line contains a `--` separator.

Prevention

Always pair trailing `-- <rustc-args>` with a single-target selector.
In wrappers, validate that exactly one target filter is present before passing args through.
Prefer `cargo rustc --lib -- <args>` over `cargo build -- <args>`.

When it happens

Trigger: Running `cargo build -- <rustc-args>` (or `cargo rustc -- <args>`) without narrowing to exactly one target, in a workspace/package where multiple root units (lib + bin, multiple bins, etc.) are selected.

Common situations: Forgetting `--lib` / `--bin NAME` when passing rustc flags; default members resolve to more than one target; passing `--` args to `cargo test`/`bench` that build several roots.

Related errors

AI-assisted analysis of rust-lang/cargo@495c385d08 (2026-08-11). Data as JSON: /api/errors/9eff207533697de0. Report an issue: GitHub.

Appendix: source

Thrown at src/ops/cargo_compile/mod.rs:590

                platform: target_data.short_name(&unit.kind).to_owned(),
                index,
                features: unit
                    .features
                    .iter()
                    .map(|s| s.as_str().to_owned())
                    .collect(),
                requested: root_unit_indexes.contains(&index),
                dependencies,
            });
        }
        let elapsed = ws.gctx().invocation_instant().elapsed().as_secs_f64();
        logger.log(LogMessage::UnitGraphFinished { elapsed });
    }

    let mut extra_compiler_args = HashMap::default();
    if let Some(args) = extra_args {
        if root_units.len() != 1 {
            anyhow::bail!(
                "extra arguments to `{}` can only be passed to one \
                 target, consider filtering\nthe package by passing, \
                 e.g., `--lib` or `--bin NAME` to specify a single target",
                extra_args_name
            );
        }
        extra_compiler_args.insert(root_units[0].clone(), args);
    }

    for unit in root_units
        .iter()
        .filter(|unit| unit.mode.is_doc() || unit.mode.is_doc_test())
        .filter(|unit| rustdoc_document_private_items || unit.target.is_bin())
    {
        // Add `--document-private-items` rustdoc flag if requested or if
        // the target is a binary. Binary crates get their private items
        // documented by default.
        let mut args = vec!["--document-private-items".into()];

View on GitHub (pinned to 495c385d08)