{"record":{"id":"aa8ee43584382e5b","repo":"vllm-project/vllm","slug":"managed-frontend-engine-count-engine-count-mus","errorCode":null,"errorMessage":"managed frontend engine count ({engine_count}) must equal data parallel size ({})","messagePattern":"managed frontend engine count \\((.+?)\\) must equal data parallel size \\((.+?)\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"rust/src/server/src/config.rs","lineNumber":254,"sourceCode":"        {\n            bail!(\n                \"max_logprobs must be non-negative or -1, got {}\",\n                max_logprobs\n            );\n        }\n        if self.data_parallel_size == 0 {\n            bail!(\"data parallel size must be at least 1\");\n        }\n        if self.data_parallel_size > usize::from(u16::MAX) + 1 {\n            bail!(\n                \"data parallel size ({}) exceeds the two-byte engine identity limit\",\n                self.data_parallel_size\n            );\n        }\n        match &self.transport_mode {\n            TransportMode::HandshakeOwner { engine_count, .. } => {\n                if *engine_count != self.data_parallel_size {\n                    bail!(\n                        \"managed frontend engine count ({engine_count}) must equal data parallel size ({})\",\n                        self.data_parallel_size\n                    );\n                }\n            }\n            TransportMode::Bootstrapped {\n                engine_start_index,\n                engine_count,\n                ..\n            } => {\n                if *engine_count == 0 {\n                    bail!(\"engine count must be at least 1\");\n                }\n                let engine_start_index = usize::try_from(*engine_start_index)\n                    .map_err(|_| anyhow::anyhow!(\"engine start index does not fit usize\"))?;\n                let engine_end_index =\n                    engine_start_index.checked_add(*engine_count).ok_or_else(|| {\n                        anyhow::anyhow!(\"engine start index + engine count overflows\")","sourceCodeStart":236,"sourceCodeEnd":272,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/rust/src/server/src/config.rs#L236-L272","documentation":"Thrown by Config::validate() when the transport mode is TransportMode::HandshakeOwner (a frontend that owns engine handshaking) and the negotiated engine_count differs from --data-parallel-size. In managed mode the frontend spawns/connects exactly data_parallel_size engines, so a mismatch means the handshake produced an inconsistent topology.","triggerScenarios":"Running the managed frontend where the handshake layer reports N engines but --data-parallel-size M with N != M — e.g. an external process injected engines into the handshake, or flags and a config file disagree. Both values are printed in the message.","commonSituations":"Mixed flag/config-file configuration where --data-parallel-size was overridden; a partially failed previous launch leaving stray engines registered in the handshake; mismatched versions of launcher and frontend agreeing on different engine counts.","solutions":["Make --data-parallel-size equal the number of engines the managed frontend actually starts.","Remove conflicting configuration sources (config file vs CLI flags) so only one defines DP size.","Kill leftover engine processes from previous runs before relaunching the managed frontend.","Check both numbers in the error message: engine_count comes from the handshake, the other from your flag."],"exampleFix":"# before (handshake reports 4 engines but flag says 2)\n--data-parallel-size 2\n\n# after\n--data-parallel-size 4","handlingStrategy":"validation","validationCode":"if let TransportMode::HandshakeOwner { engine_count, .. } = &config.transport_mode {\n    assert_eq!(*engine_count, config.data_parallel_size,\n        \"handshake engine count must equal --data-parallel-size\");\n}","typeGuard":"fn handshake_counts_agree(config: &Config) -> bool {\n    match &config.transport_mode {\n        TransportMode::HandshakeOwner { engine_count, .. } =>\n            *engine_count == config.data_parallel_size,\n        _ => true,\n    }\n}","tryCatchPattern":"if let Err(e) = config.validate() {\n    eprintln!(\"startup config invalid: {e:#}\");\n    std::process::exit(2);\n}","preventionTips":["Derive --data-parallel-size from the same source the handshake uses.","Ensure only one component owns engine count (flags XOR config file).","Clean up stray engines between launches."],"tags":["configuration","data-parallel","transport","handshake","rust","vllm","startup"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}