{"id":"9eff207533697de0","repo":"rust-lang/cargo","slug":"extra-arguments-to-can-only-be-passed-to-one","errorCode":null,"errorMessage":"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","messagePattern":"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","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"src/ops/cargo_compile/mod.rs","lineNumber":582,"sourceCode":"                platform: target_data.short_name(&unit.kind).to_owned(),\n                index,\n                features: unit\n                    .features\n                    .iter()\n                    .map(|s| s.as_str().to_owned())\n                    .collect(),\n                requested: root_unit_indexes.contains(&index),\n                dependencies,\n            });\n        }\n        let elapsed = ws.gctx().invocation_instant().elapsed().as_secs_f64();\n        logger.log(LogMessage::UnitGraphFinished { elapsed });\n    }\n\n    let mut extra_compiler_args = HashMap::default();\n    if let Some(args) = extra_args {\n        if root_units.len() != 1 {\n            anyhow::bail!(\n                \"extra arguments to `{}` can only be passed to one \\\n                 target, consider filtering\\nthe package by passing, \\\n                 e.g., `--lib` or `--bin NAME` to specify a single target\",\n                extra_args_name\n            );\n        }\n        extra_compiler_args.insert(root_units[0].clone(), args);\n    }\n\n    for unit in root_units\n        .iter()\n        .filter(|unit| unit.mode.is_doc() || unit.mode.is_doc_test())\n        .filter(|unit| rustdoc_document_private_items || unit.target.is_bin())\n    {\n        // Add `--document-private-items` rustdoc flag if requested or if\n        // the target is a binary. Binary crates get their private items\n        // documented by default.\n        let mut args = vec![\"--document-private-items\".into()];","sourceCodeStart":564,"sourceCodeEnd":600,"githubUrl":"https://github.com/rust-lang/cargo/blob/0e07a155371a6ce88ae53a2c00df940280c09a67/src/ops/cargo_compile/mod.rs#L564-L600","documentation":"Thrown when extra rustc/rustdoc arguments (supplied via target_rustc_args / target_rustdoc_args, e.g. `cargo rustc -- <ARGS>` or `cargo rustdoc -- <ARGS>`) are present but the resolved build has more than one root unit. Cargo can only forward raw compiler flags to a single target, so it requires the selection to be narrowed. Guarded at src/ops/cargo_compile/mod.rs:580-588.","triggerScenarios":"Calling `cargo rustc -- --cfg foo` (or `cargo rustdoc --`) when the default package selection yields multiple root units (e.g. a workspace default with several crates, or a package with lib+bin+tests). The check `root_units.len() != 1` triggers the bail.","commonSituations":"Running `cargo rustc -- -Zunstable-options` in a multi-crate workspace without -p/--lib/--bin. Forgetting to add a target filter when scripting rustc flags. A package that builds lib and bin by default.","solutions":["Add a single-target filter: `--lib`, `--bin NAME`, `--example NAME`, `--test NAME`, or `--bench NAME`.","Scope to one package with `-p <pkg>` plus one of the above target filters.","Drop the extra rustc args if you actually meant to build all targets."],"exampleFix":"# before\ncargo rustc -- --cfg my_flag        # multiple root units -> error\n\n# after\ncargo rustc --lib -- --cfg my_flag   # single target, ok","handlingStrategy":"validation","validationCode":"// When forwarding rustc/rustdoc args, ensure exactly one target is selected.\nfn single_target_filter(spec: &Packages, lib: bool, bin: Option<&str>) -> bool {\n    lib || bin.is_some()\n}\n// CLI: if extra args present, require --lib or --bin NAME before invoking compile.","typeGuard":"fn has_single_target_filter(opts: &ops::CompileOptions) -> bool {\n    use cargo::core::compiler::CompileMode;\n    opts.build_config.mode != CompileMode::Every\n        && (opts.spec.len() == 1 /* simplified */)\n}","tryCatchPattern":"if let Err(e) = ops::compile(ws, &opts) {\n    if e.to_string().contains(\"extra arguments\") {\n        eprintln!(\"pass --lib or --bin NAME to select a single target\");\n    }\n    return Err(e);\n}","preventionTips":["Always pair `cargo rustc -- <args>` with a target filter.","Validate that root_units.len() == 1 before forwarding extra args in tooling.","Document the single-target requirement in wrapper scripts."],"tags":["cargo","rustc-args","compilation","cli","target-selection"],"analyzedSha":"0e07a155371a6ce88ae53a2c00df940280c09a67","analyzedAt":"2026-08-06T01:46:58.334Z","schemaVersion":2}