vllm-project/vllm · error · Error

unexpected non-control output on coordinator path: {message}

Error message

unexpected non-control output on coordinator path: {message}

What it means

Error::UnexpectedCoordinatorOutput is raised inside the in-process and external coordinator loops (coordinator/inproc.rs:169, coordinator/external.rs:116 via bail_unexpected_coordinator_output!) when a message arriving on the dedicated coordinator control path is not an engine control output the coordinator state machine understands.

Source

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

    Io(#[from] std::io::Error),
    #[error("transport error")]
    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 },

View on GitHub (pinned to c794754062)

Solutions

1. Read message for the frame contents/class that failed classification
2. Verify the coordinator input/output addresses in the INIT message match what engines were configured with
3. Align engine and Rust frontend versions (coordinator protocol evolves with the codebase)
4. Ensure no other service can reach the coordinator output socket (bind to the intended interface only)

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

if let engine_core_client::Error::UnexpectedCoordinatorOutput { message } = &err {
    tracing::error!(message, "non-control traffic on coordinator path; fatal for coordinator session");
}

When it happens

Trigger: Running with CoordinatorMode::InProc (or External) and the coordinator socket receives a frame that is not a valid engine control message — e.g. a normal generation output routed to the coordinator socket by mistake, or a malformed/unrecognized control frame from an engine speaking a different protocol version.

Common situations: Version mismatch between the coordinator protocol implemented in Rust and the engine's control-message format; misconfigured engine sending request outputs on the coordinator output address; leftover/wrong process connected to the coordinator socket. Indicates traffic-classification failure, not a transient network issue.

Related errors

• cannot use in-process coordinator with bootstrapped transpor
• messagepack encode failed for {target_type}: {message}
• messagepack decode failed for {target_type}: {message}
• unexpected startup handshake message: {message}
• unexpected output on main dispatcher path: {message}

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