vllm-project/vllm · error

cannot combine `--headless` with `--data-parallel-size-local

Error message

cannot combine `--headless` with `--data-parallel-size-local 0`

What it means

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.

Source

Thrown at rust/src/cmd/src/main.rs:128

            error!("process failed with error: {:#?}", error.as_report());
            ExitCode::FAILURE
        }
    }
}

async fn async_main(cli: Cli) -> Result<()> {
    match cli.command {
        Command::Frontend(args) => vllm_server::serve(args.into_config(), shutdown_signal()).await,
        Command::Bench(BenchCommand::Serve(bench_args)) => {
            vllm_bench::prepare_process();
            vllm_bench::run(bench_args).await
        }
        Command::Serve(args) => {
            let handshake_port = args.managed_engine.resolve_handshake_port()?;

            if args.managed_engine.data_parallel_size_local == Some(0) {
                if args.headless {
                    bail!("cannot combine `--headless` with `--data-parallel-size-local 0`");
                }

                let handshake_address = args.managed_engine.handshake_address(handshake_port);
                info!(
                    %handshake_address,
                    engine_count = args.managed_engine.data_parallel_size,
                    "running Rust frontend without a managed local Python engine"
                );
                let config = args.to_frontend_config(handshake_address);
                return vllm_server::serve(config, shutdown_signal()).await;
            }

            let shutdown_timeout = args.runtime.shutdown_timeout();
            let engine_config = args.to_managed_engine_config(handshake_port);
            let handshake_address = engine_config.handshake_address();

            let engine = ManagedEngineHandle::spawn(engine_config)
                .await

View on GitHub (pinned to c794754062)

Solutions

1. Drop one of the flags: use `--headless` alone, or `--data-parallel-size-local 0` alone — both select headless operation.
2. Prefer `--headless` if you also pass engine-count/handshake options meant for the headless flow.
3. Audit launch scripts for leftover flags after upgrading the CLI.

Example fix

# before
vllm serve model --headless --data-parallel-size-local 0

# after
vllm serve model --headless

if cli.headless && cli.managed_engine.data_parallel_size_local == Some(0) {
    return Err("pass --headless or --data-parallel-size-local 0, not both");
}

When it happens

Trigger: `vllm serve ... --headless --data-parallel-size-local 0 <more>` — both flags enabling headless mode at once.

Common situations: 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.

Related errors

• {kind} parser `{name}` is not registered{}
• gpt_oss uses native Harmony output parsing; generic {kind} p
• failed to read chat template file
• chat template looks like a file path but does not exist
• startup handshake timed out while waiting for {stage} after

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/772a15e0bf757ffc. Report an issue: GitHub.