{"record":{"id":"772a15e0bf757ffc","repo":"vllm-project/vllm","slug":"cannot-combine-headless-with-data-parallel","errorCode":null,"errorMessage":"cannot combine `--headless` with `--data-parallel-size-local 0`","messagePattern":"cannot combine `--headless` with `--data-parallel-size-local 0`","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"rust/src/cmd/src/main.rs","lineNumber":128,"sourceCode":"            error!(\"process failed with error: {:#?}\", error.as_report());\n            ExitCode::FAILURE\n        }\n    }\n}\n\nasync fn async_main(cli: Cli) -> Result<()> {\n    match cli.command {\n        Command::Frontend(args) => vllm_server::serve(args.into_config(), shutdown_signal()).await,\n        Command::Bench(BenchCommand::Serve(bench_args)) => {\n            vllm_bench::prepare_process();\n            vllm_bench::run(bench_args).await\n        }\n        Command::Serve(args) => {\n            let handshake_port = args.managed_engine.resolve_handshake_port()?;\n\n            if args.managed_engine.data_parallel_size_local == Some(0) {\n                if args.headless {\n                    bail!(\"cannot combine `--headless` with `--data-parallel-size-local 0`\");\n                }\n\n                let handshake_address = args.managed_engine.handshake_address(handshake_port);\n                info!(\n                    %handshake_address,\n                    engine_count = args.managed_engine.data_parallel_size,\n                    \"running Rust frontend without a managed local Python engine\"\n                );\n                let config = args.to_frontend_config(handshake_address);\n                return vllm_server::serve(config, shutdown_signal()).await;\n            }\n\n            let shutdown_timeout = args.runtime.shutdown_timeout();\n            let engine_config = args.to_managed_engine_config(handshake_port);\n            let handshake_address = engine_config.handshake_address();\n\n            let engine = ManagedEngineHandle::spawn(engine_config)\n                .await","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/rust/src/cmd/src/main.rs#L110-L146","documentation":"CLI argument conflict in the Rust vLLM binary (`cmd/src/main.rs:128`): `--headless` runs a Rust frontend against externally managed engine processes, while `--data-parallel-size-local 0` also means 'no local Python engine'. Combining them is rejected with `bail!` because the two flags express overlapping, potentially contradictory engine-management setups and the configuration would be ambiguous.","triggerScenarios":"`vllm serve ... --headless --data-parallel-size-local 0 <more>` — both flags enabling headless mode at once.","commonSituations":"Scripts migrated from one headless style to the other with the old flag left behind; copy-pasted launch commands combining flags from different vLLM versions/runbooks.","solutions":["Drop one of the flags: use `--headless` alone, or `--data-parallel-size-local 0` alone — both select headless operation.","Prefer `--headless` if you also pass engine-count/handshake options meant for the headless flow.","Audit launch scripts for leftover flags after upgrading the CLI."],"exampleFix":"# before\nvllm serve model --headless --data-parallel-size-local 0\n\n# after\nvllm serve model --headless","handlingStrategy":"validation","validationCode":"if cli.headless && cli.managed_engine.data_parallel_size_local == Some(0) {\n    return Err(\"pass --headless or --data-parallel-size-local 0, not both\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep one canonical headless launch command per deployment and template it.","Add a launch-script lint that rejects flag combinations the CLI documents as mutually exclusive."],"tags":["rust","cli","configuration","headless","argument-conflict"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}