vllm-project/vllm · error · Error

external coordinator mode is not implemented yet

Error message

external coordinator mode is not implemented yet

What it means

Error::UnsupportedExternalCoordinator is returned by EngineCoreClient::connect (client.rs:241-243) when coordinator_mode is Some(CoordinatorMode::External { .. }) with TransportMode::HandshakeOwner. External coordinator support is simply not implemented yet in the Rust client, so the combination is rejected up front rather than half-working.

Source

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

    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 {
        rank: u32,
        connected_ranks: Vec<u32>,
    },
    #[error("engine-core output dispatcher closed: {message}")]

View on GitHub (pinned to c794754062)

Solutions

1. Set coordinator_mode to None or Some(CoordinatorMode::InProc) for now
2. If external coordinator semantics are required, keep using the Python frontend until the Rust client implements it
3. Track the upstream rust-vllm frontend repository for External coordinator support and re-enable afterwards

Example fix

// before
coordinator_mode: Some(CoordinatorMode::External { address }),

// after
coordinator_mode: Some(CoordinatorMode::InProc),

fn coordinator_mode_supported(mode: &Option<CoordinatorMode>) -> bool {
    !matches!(mode, Some(CoordinatorMode::External { .. }))
}

fn is_unsupported_coordinator(e: &engine_core_client::Error) -> bool {
    matches!(e, engine_core_client::Error::UnsupportedExternalCoordinator)
}

match EngineCoreClient::connect(config).await {
    Err(e @ engine_core_client::Error::UnsupportedExternalCoordinator) => {
        tracing::error!("external coordinator not implemented; falling back to InProc");
        let config = config_with_coordinator(config, Some(CoordinatorMode::InProc));
        EngineCoreClient::connect(config).await?
    }
    other => other?,
}

When it happens

Trigger: Calling EngineCoreClient::connect with config.coordinator_mode = Some(CoordinatorMode::External { .. }) and transport_mode = TransportMode::HandshakeOwner. Note the check only exists on the HandshakeOwner arm; with TransportMode::Bootstrapped an External coordinator is silently ignored, which can mask the mistake.

Common situations: Porting a Python deployment that uses an external DP coordinator to the Rust frontend before support lands. Users assuming parity with Python vLLM's external coordinator feature. The error is deterministic — a capability gap, not an environment issue.

Related errors

• coordinator requires a Python-compatible two-byte engine id,
• {kind} parser `{name}` is not registered{}
• gpt_oss uses native Harmony output parsing; generic {kind} p
• failed to read chat template file
• chat template looks like a file path but does not exist

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