{"record":{"id":"25e6ad3e2a080a25","repo":"vllm-project/vllm","slug":"unexpected-output-on-main-dispatcher-path-messag","errorCode":null,"errorMessage":"unexpected output on main dispatcher path: {message}","messagePattern":"unexpected output on main dispatcher path: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"rust/src/engine-core-client/src/error.rs","lineNumber":54,"sourceCode":"    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 },\n    #[error(\"request `{request_id}` is already in flight\")]\n    DuplicateRequestId { request_id: String },\n    #[error(\n        \"data parallel rank {rank} is not connected to this frontend; connected ranks: {connected_ranks:?}\"","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/rust/src/engine-core-client/src/error.rs#L36-L72","documentation":"Error::UnexpectedDispatcherOutput is the mirror of the coordinator variant for the main output path: the dispatcher task that fans engine outputs out to per-request channels expects only recognized output/control frames, and anything unrecognized on the main dispatcher path becomes this error (it is treated as a fatal client error in tests/client.rs:432 alongside EngineCoreDead).","triggerScenarios":"The client's dispatcher background task receives an EngineCoreOutputs frame it cannot classify — for example a control frame arriving on the main output socket instead of the coordinator socket, or a new output message kind emitted by a newer Python engine that the Rust dispatcher does not know.","commonSituations":"vLLM added a new output/control message type and the Rust crate predates it; coordinator-enabled engines misrouting control traffic to the main output path; corrupted frames decoding into an unexpected union shape. After it fires the client is generally unusable (fatal class in tests).","solutions":["Align Rust frontend and Python engine versions — this almost always indicates schema drift","Inspect message for the unrecognized frame's decoded shape to identify which new message type is involved","Check coordinator address wiring if control frames are appearing on the main path","Rebuild the client after fixing; treat as fatal, not retriable"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"fn is_dispatcher_output_error(e: &engine_core_client::Error) -> bool {\n    matches!(e, engine_core_client::Error::UnexpectedDispatcherOutput { .. })\n}","tryCatchPattern":"match result {\n    Err(e @ engine_core_client::Error::UnexpectedDispatcherOutput { message }) => {\n        tracing::error!(message, \"unrecognized output on main path; rebuild client\"); // fatal class per tests\n    }\n    other => other?,\n}","preventionTips":["Version-lock engine and frontend; new output kinds from a newer engine decode into this error","Verify coordinator/main output address wiring whenever coordinator mode is enabled","Classify this error as fatal in monitoring (same bucket as EngineCoreDead in tests/client.rs:432)"],"tags":["rust","dispatcher","output-routing","version-skew","protocol"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}