vllm-project/vllm · error · Error

engine input registration timed out after {timeout:?}

Error message

engine input registration timed out after {timeout:?}

What it means

Error::InputRegistrationTimeout is raised in transport.rs:478-482 (wait_for_input_registrations) when, after the READY phase, an engine fails to connect and register on the shared frontend input socket within ready_timeout. Registration frames are [identity, ready-payload] pairs validated against the expected engine set.

Source

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

    ValueDecode(#[from] rmpv::decode::Error),
    #[error("messagepack ext value decode failed: {message}")]
    ExtValueDecode { message: String },
    #[error("invalid structured outputs params: {message}")]
    InvalidStructuredOutputsParams { message: String },
    #[error("io error")]
    Io(#[from] std::io::Error),
    #[error("transport error")]
    Transport(#[from] zeromq::ZmqError),
    #[error("ZMQ runtime task failed")]
    ZmqRuntimeTask(#[from] tokio::task::JoinError),
    #[error("engine core reported fatal failure")]
    EngineCoreDead,
    #[error("startup handshake timed out while waiting for {stage} after {timeout:?}")]
    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,

View on GitHub (pinned to c794754062)

Solutions

1. Verify the input/output addresses handed to engines (INIT message in handshake mode; supervisor-provided addresses in bootstrapped mode) are reachable from engine containers
2. In bootstrapped mode, check engine_start_index + engine_count match the supervisor's engine rank layout (see connect_bootstrapped validation)
3. Raise ready_timeout if engine connect is just slow
4. Check engine logs for the moment after READY — a crash there produces exactly this timeout

fn bootstrapped_indices_valid(start: u32, count: usize) -> bool {
    count >= 1 && start <= u16::MAX as u32 && (start as usize + count) <= u16::MAX as usize + 1
}

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

if matches!(err, engine_core_client::Error::InputRegistrationTimeout { timeout }) {
    tracing::error!(?timeout, "engines finished handshake but never registered on inputs; check network reachability");
}

When it happens

Trigger: The final step of connect_handshake (step 6) or connect_bootstrapped: each engine must send its 2-frame registration on the input RouterSocket within ready_timeout. Any engine missing that deadline triggers this error with the configured timeout embedded.

Common situations: Engine received INIT addresses it cannot reach (firewall, advertised_host wrong, docker network isolation), engine crashed between READY and connecting to inputs, or (bootstrapped mode) engine_start_index/engine_count disagree with what the supervisor launched so the expected identity set never matches. Distinct from HandshakeTimeout: the engine finished the handshake but never dialed the input socket.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• startup handshake timed out while waiting for {stage} after
• cannot use in-process coordinator with bootstrapped transpor
• transport error
• invalid --allowed-methods value {method:?}: {e}
• invalid --allowed-headers value {header:?}: {e}

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