{"record":{"id":"a228f8a41d489b09","repo":"vllm-project/vllm","slug":"io-error","errorCode":null,"errorMessage":"io error","messagePattern":"io error","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"rust/src/engine-core-client/src/error.rs","lineNumber":33,"sourceCode":"#[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,\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 },","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/rust/src/engine-core-client/src/error.rs#L15-L51","documentation":"Error::Io is the #[from] wrapper for std::io::Error inside the crate's unified error enum. Any I/O failure inside the client (socket option errors, fd errors from the ZMQ layer surfaced as io::Error, spawn/read failures) is folded into this variant, so the Display text 'io error' alone is intentionally terse — the source chain holds the real cause.","triggerScenarios":"Any ? conversion from a std::io::Result inside engine-core-client: binding helpers, ZMQ socket operations that report io errors, or task plumbing. Unlike Transport (zeromq::ZmqError), this fires on plain OS-level I/O problems.","commonSituations":"File descriptor exhaustion after opening many engine sockets, permission errors on IPC paths, or an OS-level broken pipe surfacing outside the zeromq error type. Because Display hides the cause, users often misdiagnose it; always inspect the error source.","solutions":["Inspect the error chain (err.source() / {:?} debug print) — the io::Error kind and message identify the real failure","Check fd limits (ulimit -n) when running many engines","Verify IPC/tcp bind paths and permissions if it occurs during connect","File an issue with the full chain if the underlying io::Error is unclear from the code path"],"exampleFix":"// before\nmatch client_result {\n    Err(e) => log::error!(\"failed: {e}\"), // prints only 'io error'\n}\n\n// after\nmatch client_result {\n    Err(e) => {\n        let mut chain = e.to_string();\n        let mut src = std::error::Error::source(&e);\n        while let Some(s) = src { chain.push_str(&format!(\": {s}\")); src = s.source(); }\n        log::error!(\"failed: {chain}\");\n    }\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"fn is_io_error(e: &engine_core_client::Error) -> bool {\n    matches!(e, engine_core_client::Error::Io(_))\n}","tryCatchPattern":"if let engine_core_client::Error::Io(io) = &err {\n    tracing::error!(kind = ?io.kind(), %io, \"io failure\"); // unwrap the source for real diagnostics\n}","preventionTips":["Always log the full error chain; 'io error' Display is intentionally terse","Raise ulimit -n before running many engines","Monitor fd usage and socket counts in long-running frontends"],"tags":["rust","io","error-handling","diagnostics"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}