{"record":{"id":"aab595c5751c80c4","repo":"vllm-project/vllm","slug":"coordinator-requires-a-python-compatible-two-byte","errorCode":null,"errorMessage":"coordinator requires a Python-compatible two-byte engine id, got {engine_id:?}","messagePattern":"coordinator requires a Python-compatible two-byte engine id, got (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"rust/src/engine-core-client/src/error.rs","lineNumber":56,"sourceCode":"    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:?}\"\n    )]\n    InvalidDataParallelRank {","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/rust/src/engine-core-client/src/error.rs#L38-L74","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure all engines use standard two-byte index identities derived from their data-parallel rank (EngineId::from_engine_index)","In bootstrapped mode, keep engine_start_index + engine_count within the u16 range so synthesized ids stay index-shaped","Do not mix coordinator mode with engines whose ids were hand-assigned","Reconnect with corrected identity configuration; existing connections with bad ids will keep failing"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"fn engine_id_is_index_shaped(id: &[u8]) -> bool {\n    id.len() == 2\n}","typeGuard":"fn is_unsupported_engine_id(e: &engine_core_client::Error) -> bool {\n    matches!(e, engine_core_client::Error::UnsupportedCoordinatorEngineId { .. })\n}","tryCatchPattern":"if let engine_core_client::Error::UnsupportedCoordinatorEngineId { engine_id } = &err {\n    tracing::error!(?engine_id, \"engine id lacks two-byte index form; coordinator cannot schedule it\");\n}","preventionTips":["Always generate engine ids via EngineId::from_engine_index(rank)","Keep bootstrapped engine_start_index + engine_count within u16 range","Do not enable coordinator mode alongside hand-assigned identity schemes"],"tags":["rust","coordinator","identity","configuration"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}