{"record":{"id":"91742d9c410a89ca","repo":"vllm-project/vllm","slug":"unexpected-engine-id-in-startup-handshake-expecte","errorCode":null,"errorMessage":"unexpected engine id in startup handshake: expected {expected:?}, got {actual:?}","messagePattern":"unexpected engine id in startup handshake: expected (.+?), got (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"rust/src/engine-core-client/src/error.rs","lineNumber":48,"sourceCode":"    ExtValueDecode { message: String },\n    #[error(\"invalid structured outputs params: {message}\")]\n    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    },","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/rust/src/engine-core-client/src/error.rs#L30-L66","documentation":"Error::UnexpectedHandshakeIdentity carries expected and actual engine id bytes and is raised by decode_handshake_message (transport.rs:420-427) when a handshake frame arrives with a ZMQ routing identity different from the one expected in contexts where the peer identity is already pinned (expected_id is Some).","triggerScenarios":"Receiving a handshake message on a socket where the frontend already knows the engine's identity, but frames[0] (the ZMQ identity frame) does not match — e.g. a duplicate or misconfigured engine reusing another engine's socket, or an engine restarted with a fresh identity while stale registrations are still in flight.","commonSituations":"Two engines configured with the same engine id (copy-paste of worker configs), a restarted engine whose identity changed while the frontend still expects the old one, or leftover sockets from a previous cluster run still sending frames. The expected/got byte arrays in the message directly show the collision.","solutions":["Compare expected vs actual byte arrays: identical ids from two sources = duplicate engine id configuration","Ensure each engine derives a unique identity (engine index/rank) and no ids collide across the fleet","Tear down stale sockets/processes from previous runs before reconnecting","If an engine legitimately restarted, restart the frontend client too so identity expectations reset"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"fn unique_engine_ids(ids: &[Vec<u8>]) -> bool {\n    let mut seen = std::collections::HashSet::new();\n    ids.iter().all(|id| seen.insert(id.clone()))\n}","typeGuard":"fn is_identity_mismatch(e: &engine_core_client::Error) -> bool {\n    matches!(e, engine_core_client::Error::UnexpectedHandshakeIdentity { .. })\n}","tryCatchPattern":"if let engine_core_client::Error::UnexpectedHandshakeIdentity { expected, actual } = &err {\n    tracing::error!(?expected, ?actual, \"engine identity collision; restart frontend with clean identity set\");\n}","preventionTips":["Derive every engine id from its unique rank/index; never hand-assign overlapping ids","Fully tear down sockets and processes from previous cluster runs before reconnecting","Treat identity mismatch as fatal for the connect attempt; restart both sides"],"tags":["rust","handshake","identity","configuration","duplicate"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}