vllm-project/vllm · critical

cannot use in-process coordinator with bootstrapped transpor

Error message

cannot use in-process coordinator with bootstrapped transport mode

What it means

This is a hard panic in EngineCoreClient::connect (rust/src/engine-core-client/src/client.rs:266). It fires when the caller supplies TransportMode::Bootstrapped (addresses and engine indices already fixed by an external supervisor) together with coordinator_mode = Some(CoordinatorMode::InProc). The in-process coordinator is only wired into the handshake-owned transport path (connect_handshake), so the combination is a programming/configuration error and the client aborts instead of continuing in a broken state.

Source

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

                    *engine_count,
                    advertised_host,
                    local_input_address.as_deref(),
                    local_output_address.as_deref(),
                    enable_inproc_coordinator,
                    *ready_timeout,
                )
                .await?
            }

            TransportMode::Bootstrapped {
                input_address,
                output_address,
                engine_start_index,
                engine_count,
                ready_timeout,
            } => {
                if let Some(CoordinatorMode::InProc) = config.coordinator_mode {
                    panic!("cannot use in-process coordinator with bootstrapped transport mode")
                }

                transport::connect_bootstrapped(
                    input_address,
                    output_address,
                    *engine_start_index,
                    *engine_count,
                    *ready_timeout,
                )
                .await?
            }
        };

        Self::from_connected(config, connected).await
    }

    /// Create a new client instance from the connected transport state after
    /// the startup handshake completes.

View on GitHub (pinned to c794754062)

Solutions

1. Set coordinator_mode to None (or Some(CoordinatorMode::External { .. }), which is tolerated but unimplemented elsewhere) when using TransportMode::Bootstrapped
2. If you need the in-process coordinator, switch transport_mode to TransportMode::HandshakeOwner { handshake_address, advertised_host, engine_count, ready_timeout, .. }
3. Fix the config builder/CLI parsing so these two fields cannot disagree, and add a unit test asserting connect rejects (rather than panics on) the combination

Example fix

// before
let config = EngineCoreClientConfig {
    transport_mode: TransportMode::Bootstrapped { input_address, output_address, engine_start_index, engine_count, ready_timeout },
    coordinator_mode: Some(CoordinatorMode::InProc),
};
let client = EngineCoreClient::connect(config).await?; // panics

// after
let config = EngineCoreClientConfig {
    transport_mode: TransportMode::Bootstrapped { input_address, output_address, engine_start_index, engine_count, ready_timeout },
    coordinator_mode: None,
};
let client = EngineCoreClient::connect(config).await?;

fn assert_config_compatible(config: &EngineCoreClientConfig) -> Result<()> {
    if matches!(config.transport_mode, TransportMode::Bootstrapped { .. })
        && matches!(config.coordinator_mode, Some(CoordinatorMode::InProc))
    {
        return Err(anyhow::anyhow!("in-process coordinator requires HandshakeOwner transport"));
    }
    Ok(())
}

fn is_bad_coordinator_combo(c: &EngineCoreClientConfig) -> bool {
    matches!(c.transport_mode, TransportMode::Bootstrapped { .. })
        && matches!(c.coordinator_mode, Some(CoordinatorMode::InProc))
}

When it happens

Trigger: Calling EngineCoreClient::connect(config) where config.transport_mode is TransportMode::Bootstrapped { .. } and config.coordinator_mode is Some(CoordinatorMode::InProc). Note that CoordinatorMode::External is silently accepted here (coordinator is simply None on this path), but InProc panics immediately during connect.

Common situations: Building a config from a supervisor or CLI where transport mode defaults to bootstrapped while a coordinator flag (e.g. --coordinator inproc / data-parallel coordinator enable) is still set. Copy-pasting a HandshakeOwner config and only swapping the transport variant. Migrating from the handshake-owned bootstrap to Python-managed AsyncMPClient-style bootstrap without clearing the coordinator option.

Related errors

• managed frontend engine count ({engine_count}) must equal da
• engine count must be at least 1
• engine start index does not fit usize
• engine start index + engine count overflows
• connected engine range [{engine_start_index}, {engine_end_in

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