{"record":{"id":"0b0461c388ac031f","repo":"vllm-project/vllm","slug":"unexpected-startup-handshake-message-message","errorCode":null,"errorMessage":"unexpected startup handshake message: {message}","messagePattern":"unexpected startup handshake message: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"rust/src/engine-core-client/src/error.rs","lineNumber":50,"sourceCode":"    InvalidStructuredOutputsParams { message: String },\n    #[error(\"io error\")]\n    Io(#[from] std::io::Error),\n    #[error(\"transport error\")]\n    Transport(#[from] zeromq::ZmqError),\n    #[error(\"ZMQ runtime task failed\")]\n    ZmqRuntimeTask(#[from] tokio::task::JoinError),\n    #[error(\"engine core reported fatal failure\")]\n    EngineCoreDead,\n    #[error(\"startup handshake timed out while waiting for {stage} after {timeout:?}\")]\n    HandshakeTimeout {\n        stage: &'static str,\n        timeout: Duration,\n    },\n    #[error(\"engine input registration timed out after {timeout:?}\")]\n    InputRegistrationTimeout { timeout: Duration },\n    #[error(\"unexpected engine id in startup handshake: expected {expected:?}, got {actual:?}\")]\n    UnexpectedHandshakeIdentity { expected: Vec<u8>, actual: Vec<u8> },\n    #[error(\"unexpected startup handshake message: {message}\")]\n    UnexpectedHandshakeMessage { message: String },\n    #[error(\"unexpected non-control output on coordinator path: {message}\")]\n    UnexpectedCoordinatorOutput { message: String },\n    #[error(\"unexpected output on main dispatcher path: {message}\")]\n    UnexpectedDispatcherOutput { message: String },\n    #[error(\"coordinator requires a Python-compatible two-byte engine id, got {engine_id:?}\")]\n    UnsupportedCoordinatorEngineId { engine_id: Vec<u8> },\n    #[error(\"unsupported auxiliary frame(s): expected 1 frame, got {frame_count}\")]\n    UnsupportedAuxFrames { frame_count: usize },\n    #[error(\"external coordinator mode is not implemented yet\")]\n    UnsupportedExternalCoordinator,\n    #[error(\"unsupported field `{field}` in {context}\")]\n    UnsupportedField {\n        context: &'static str,\n        field: &'static str,\n    },\n    #[error(\"engine control channel closed unexpectedly: {message}\")]\n    ControlClosed { message: String },","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/rust/src/engine-core-client/src/error.rs#L32-L68","documentation":"Error::UnexpectedHandshakeMessage is the catch-all for structurally invalid handshake traffic: wrong frame count (transport.rs:414-416), unexpected status strings (245, 295), duplicate HELLO/READY sequencing violations (204-292), registration from unexpected engine ids (493-497), and bootstrapped-mode arithmetic limits like engine_start_index not fitting u16 or engine_start_index + engine_count exceeding u16::MAX+1 (transport.rs:337-354). Also used by mock_engine.rs for peer identity issues.","triggerScenarios":"Any deviation from the HELLO→INIT→(gate)→READY→input-registration protocol: a frame that is not 2 parts, a status other than HELLO/READY, READY before the coordinator gate opens, duplicate HELLO after INIT, input registration from an id not in the pending set, or bootstrapped engine_start_index/engine_count outside the two-byte identity range.","commonSituations":"Version mismatch where the Python engine speaks an older/newer handshake protocol (e.g. pre/post vLLM commit c8d98f81). Race conditions at startup where a restarted engine re-HELLOs. Bootstrapped deployments with more than 65535 engines or a start index near u16::MAX — the message text names the exact violation.","solutions":["Read message: it states the exact protocol violation (frame count, status, engine id, or index overflow)","Align Rust frontend and Python engine versions so the handshake protocol matches","For index-overflow messages, reduce engine_count or lower engine_start_index in the supervisor config","Capture traffic with RUST_LOG=engine_core_client=trace to see the offending frames"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"fn bootstrapped_start_index_fits(start: u32, count: usize) -> Option<String> {\n    u16::try_from(start).err().map(|_| \"engine_start_index exceeds u16\".into())\n        .or_else(|| (start as usize + count > u16::MAX as usize + 1)\n            .then(|| \"start+count exceeds u16\".into()))\n}","typeGuard":"fn is_unexpected_handshake_message(e: &engine_core_client::Error) -> bool {\n    matches!(e, engine_core_client::Error::UnexpectedHandshakeMessage { .. })\n}","tryCatchPattern":"match result {\n    Err(engine_core_client::Error::UnexpectedHandshakeMessage { message }) => {\n        tracing::error!(message, \"handshake protocol violation; likely engine/frontend version mismatch\");\n    }\n    other => other?,\n}","preventionTips":["Lock engine and frontend versions in lockstep; the handshake protocol changes with vLLM commits (e.g. c8d98f81)","Validate bootstrapped index arithmetic before calling connect (see validationCode)","Run RUST_LOG=engine_core_client=trace during first bring-up to capture offending handshake frames"],"tags":["rust","handshake","protocol","validation","version-skew"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}