{"record":{"id":"01c7ca0c93863a00","repo":"vllm-project/vllm","slug":"messagepack-decode-failed-for-target-type-mess","errorCode":null,"errorMessage":"messagepack decode failed for {target_type}: {message}","messagePattern":"messagepack decode failed for (.+?): (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"rust/src/engine-core-client/src/error.rs","lineNumber":22,"sourceCode":"use std::sync::Arc;\nuse std::time::Duration;\n\nuse thiserror::Error;\nuse thiserror_ext::Macro;\n\nuse crate::protocol::utility::UtilityCallId;\n\npub type Result<T> = std::result::Result<T, Error>;\n\n/// Public error type for the Rust engine-core client.\n#[derive(Debug, Error, Macro)]\npub enum Error {\n    #[error(\"messagepack encode failed for {target_type}: {message}\")]\n    Encode {\n        target_type: &'static str,\n        message: String,\n    },\n    #[error(\"messagepack decode failed for {target_type}: {message}\")]\n    Decode {\n        target_type: &'static str,\n        message: String,\n    },\n    #[error(\"messagepack value decode failed\")]\n    ValueDecode(#[from] rmpv::decode::Error),\n    #[error(\"messagepack ext value decode failed: {message}\")]\n    ExtValueDecode { message: String },\n    #[error(\"invalid structured outputs params: {message}\")]\n    InvalidStructuredOutputsParams { message: String },\n    #[error(\"io error\")]\n    Io(#[from] std::io::Error),\n    #[error(\"transport error\")]\n    Transport(#[from] zeromq::ZmqError),\n    #[error(\"ZMQ runtime task failed\")]\n    ZmqRuntimeTask(#[from] tokio::task::JoinError),\n    #[error(\"engine core reported fatal failure\")]\n    EngineCoreDead,","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/rust/src/engine-core-client/src/error.rs#L4-L40","documentation":"A MessagePack deserialization failure. Every frame received from the engine is decoded via rmp_serde::from_slice (rust/src/engine-core-client/src/protocol/mod.rs:66), and unknown EngineCoreOutput shapes map to Error::Decode in protocol/output.rs:299. target_type tells you which struct failed to materialize; message carries the underlying rmp_serde error.","triggerScenarios":"The engine sends bytes that do not deserialize into the expected type: decoding a ReadyMessage/EngineCoreReadyResponse handshake payload, an EngineCoreOutputs frame with an unrecognized message union tag (output.rs:299 catch-all), or any response whose field types differ from the Rust struct.","commonSituations":"Version skew: Python vLLM added/renamed a wire field and the Rust crate has not caught up (see the comment at transport.rs:464 referencing vLLM commit c8d98f81 changing the handshake payload). A mismatched vLLM image vs crate version. Unexpected error payloads (e.g. tracebacks) arriving on the output socket.","solutions":["Pin the vLLM/Python engine version to one the Rust crate was built against","Inspect message and target_type: an 'unknown variant' points to a new message kind; 'invalid type' points to a changed field","Extend the corresponding Rust struct/enum (usually with #[serde(default)] or a new variant) and add a decoding test with the raw frame","Capture the raw frame with tracing (RUST_LOG=engine_core_client=trace) to feed a reproduction"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"fn is_decode_error(e: &engine_core_client::Error) -> bool {\n    matches!(e, engine_core_client::Error::Decode { .. })\n}","tryCatchPattern":"match result {\n    Err(engine_core_client::Error::Decode { target_type, message }) => {\n        tracing::error!(target_type, message, \"wire format mismatch; check engine version\");\n        return; // do not retry: deterministic schema mismatch\n    }\n    other => other?,\n}","preventionTips":["Version-lock the Python vLLM image and the Rust crate in CI","Add golden-frame decode tests for every message type (pattern in protocol/logprobs/tests.rs)","Log target_type + raw message length whenever decode fails, to correlate with engine logs"],"tags":["rust","deserialization","messagepack","version-skew","protocol"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}