vllm-project/vllm · error · Error

coordinator requires a Python-compatible two-byte engine id,

Error message

coordinator requires a Python-compatible two-byte engine id, got {engine_id:?}

What it means

Error::UnsupportedCoordinatorEngineId is raised by both coordinator implementations (coordinator/inproc.rs:91-95 and coordinator/external.rs:92) when the engine id chosen to receive the first request of a DP wave cannot be converted to a two-byte engine index. The coordinator protocol identifies engines by a u16 index compatible with Python data-parallel ranks, so ids that do not encode such an index cannot participate in wave scheduling.

Source

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

    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:?}"
    )]
    InvalidDataParallelRank {

View on GitHub (pinned to c794754062)

Solutions

1. Ensure all engines use standard two-byte index identities derived from their data-parallel rank (EngineId::from_engine_index)
2. In bootstrapped mode, keep engine_start_index + engine_count within the u16 range so synthesized ids stay index-shaped
3. Do not mix coordinator mode with engines whose ids were hand-assigned
4. Reconnect with corrected identity configuration; existing connections with bad ids will keep failing

fn engine_id_is_index_shaped(id: &[u8]) -> bool {
    id.len() == 2
}

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

if let engine_core_client::Error::UnsupportedCoordinatorEngineId { engine_id } = &err {
    tracing::error!(?engine_id, "engine id lacks two-byte index form; coordinator cannot schedule it");
}

When it happens

Trigger: Using CoordinatorMode::InProc or External: notify_first_request picks a target engine (e.g. least-loaded via register in client/state.rs) and calls engine_id.engine_index(); if the ConnectedEngine's id bytes are not a two-byte index form, this error is returned and the wave broadcast is abandoned.

Common situations: Custom or externally-synthesized engine identities (arbitrary byte strings from a nonstandard handshake) used together with coordinator mode. Mixed fleets where some engines registered with Python-style ids and others did not. It is a configuration/identity-scheme mismatch, not transient.

Related errors

• unexpected engine id in startup handshake: expected {expecte
• external coordinator mode is not implemented yet
• {kind} parser `{name}` is not registered{}
• gpt_oss uses native Harmony output parsing; generic {kind} p
• failed to read chat template file

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