vllm-project/vllm · error · Error

unsupported field `{field}` in {context}

Error message

unsupported field `{field}` in {context}

What it means

Error::UnsupportedField { context, field } is a staged-support guard: EngineCoreRequest::validate (protocol/request.rs:134-141) rejects requests containing fields the first-stage client deliberately does not support — currently prompt_embeds is the only checked field ('unsupported field `prompt_embeds` in EngineCoreRequest'). It fails fast at validation time instead of sending a request the engine/client would mishandle.

Source

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

        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}")]
    DispatcherClosed { message: String },
    #[error("engine-core client is closed: {message}")]

View on GitHub (pinned to c794754062)

Solutions

1. Tokenize embeddings' source text upstream and send token ids via the normal prompt fields, leaving prompt_embeds as None
2. Audit the frontend for code that sets prompt_embeds and gate it behind a feature check
3. Watch the crate's roadmap: when the field is supported, validate() stops rejecting it and no caller change is needed

Example fix

// before
let req = EngineCoreRequest { prompt_embeds: Some(embeds), prompt: None, ..base };

// after
let req = EngineCoreRequest { prompt_embeds: None, prompt: Some(token_ids), ..base };

fn request_fields_supported(req: &EngineCoreRequest) -> bool {
    req.validate().is_ok()
}

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

match req.validate() {
    Err(e @ engine_core_client::Error::UnsupportedField { context, field }) => {
        return bad_request(400, format!("{context} does not support `{field}`"));
    }
    other => other?,
}

When it happens

Trigger: Submitting a request whose prompt_embeds is Some(..) through the Rust engine-core client; validate() runs on the request path before encoding, returning this error without touching the network.

Common situations: Porting a Python workload that passes prompt embedding tensors directly (prompt_embeds) instead of token ids; frontends that populate every optional field defensively. The field is explicitly unsupported in the first stage of this client, so this is an API-capability error, not corruption.

Related errors

• invalid structured outputs params: {message}
• this model's maximum context length is {max_model_len} token
• duplicate tool name `{name}`
• tool_choice requires at least one available tool
• tool_choice function `{name}` was not found in the available

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