vllm-project/vllm · error · Error

unexpected output on main dispatcher path: {message}

Error message

unexpected output on main dispatcher path: {message}

What it means

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).

Source

Thrown at rust/src/engine-core-client/src/error.rs:54

    Transport(#[from] zeromq::ZmqError),
    #[error("ZMQ runtime task failed")]
    ZmqRuntimeTask(#[from] tokio::task::JoinError),
    #[error("engine core reported fatal failure")]
    EngineCoreDead,
    #[error("startup handshake timed out while waiting for {stage} after {timeout:?}")]
    HandshakeTimeout {
        stage: &'static str,
        timeout: Duration,
    },
    #[error("engine input registration timed out after {timeout:?}")]
    InputRegistrationTimeout { timeout: Duration },
    #[error("unexpected engine id in startup handshake: expected {expected:?}, got {actual:?}")]
    UnexpectedHandshakeIdentity { expected: Vec<u8>, actual: Vec<u8> },
    #[error("unexpected startup handshake message: {message}")]
    UnexpectedHandshakeMessage { message: String },
    #[error("unexpected non-control output on coordinator path: {message}")]
    UnexpectedCoordinatorOutput { message: String },
    #[error("unexpected output on main dispatcher path: {message}")]
    UnexpectedDispatcherOutput { message: String },
    #[error("coordinator requires a Python-compatible two-byte engine id, got {engine_id:?}")]
    UnsupportedCoordinatorEngineId { engine_id: Vec<u8> },
    #[error("unsupported auxiliary frame(s): expected 1 frame, got {frame_count}")]
    UnsupportedAuxFrames { frame_count: usize },
    #[error("external coordinator mode is not implemented yet")]
    UnsupportedExternalCoordinator,
    #[error("unsupported field `{field}` in {context}")]
    UnsupportedField {
        context: &'static str,
        field: &'static str,
    },
    #[error("engine control channel closed unexpectedly: {message}")]
    ControlClosed { message: String },
    #[error("request `{request_id}` is already in flight")]
    DuplicateRequestId { request_id: String },
    #[error(
        "data parallel rank {rank} is not connected to this frontend; connected ranks: {connected_ranks:?}"

View on GitHub (pinned to c794754062)

Solutions

1. Align Rust frontend and Python engine versions — this almost always indicates schema drift
2. Inspect message for the unrecognized frame's decoded shape to identify which new message type is involved
3. Check coordinator address wiring if control frames are appearing on the main path
4. Rebuild the client after fixing; treat as fatal, not retriable

fn is_dispatcher_output_error(e: &engine_core_client::Error) -> bool {
    matches!(e, engine_core_client::Error::UnexpectedDispatcherOutput { .. })
}

match result {
    Err(e @ engine_core_client::Error::UnexpectedDispatcherOutput { message }) => {
        tracing::error!(message, "unrecognized output on main path; rebuild client"); // fatal class per tests
    }
    other => other?,
}

When it happens

Trigger: 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.

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

Related errors

• messagepack decode failed for {target_type}: {message}
• unexpected startup handshake message: {message}
• messagepack encode failed for {target_type}: {message}
• messagepack ext value decode failed: {message}
• unexpected non-control output on coordinator path: {message}

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