What causes "OpenAI server shut down unexpectedly without error" in vllm-project/vllm?

Inspect earlier logs: the serve task logged its own shutdown reason before returning Ok.

OpenAI server shut down unexpectedly without error

Error message

OpenAI server shut down unexpectedly without error

What it means

Runtime shutdown error in the managed-engine serve path (`cmd/src/main.rs:186`): the API-server task ended with `Ok(())` — i.e. it shut itself down cleanly — but no shutdown signal was requested and no error was reported. The supervisor treats a spontaneous clean exit as a fault because serve should run until cancelled. Surfaced as `Err` with context "OpenAI server shut down unexpectedly" at line ~212.

Source

Thrown at rust/src/cmd/src/main.rs:186

            };

            let shutdown_reason = tokio::select! {
                biased;

                // Received shutdown signal via Ctrl-C or SIGTERM.
                _ = shutdown.cancelled() => ShutdownReason::Signal,

                // Engine process exited unexpectedly.
                status = engine.wait_for_exit() => {
                    warn!(%status, "managed Python headless engine exited, shutting down...");
                    ShutdownReason::EngineExited(status)
                }

                // Serve task exited unexpectedly.
                serve_result = &mut serve_task => {
                    let serve_result = serve_result.context("serve task join failed")?;
                    match serve_result {
                        Ok(()) => ShutdownReason::Server(anyhow!("OpenAI server shut down unexpectedly without error")),
                        Err(error) => ShutdownReason::Server(error),
                    }
                }
            };
            // Regardless of the shutdown reason, broadcast shutdown signal here to ensure
            // that all serving tasks are notified.
            shutdown.cancel();

            // Shutdown begins. Terminate the managed engine first.
            engine.shutdown(shutdown_timeout).await?;
            info!("managed engine shut down gracefully");
            // Wait for the API server to shut down gracefully by draining in-flight
            // requests.
            if !matches!(shutdown_reason, ShutdownReason::Server(_)) {
                serve_task.await.context("serve task join failed")??;
            }

            match shutdown_reason {

View on GitHub (pinned to c794754062)

Solutions

Inspect earlier logs: the serve task logged its own shutdown reason before returning Ok.
Check the server config actually enables an API listener (host/port, api keys) so the task has something to serve.
Reproduce with `RUST_LOG=debug` / `vllm_server` tracing to see which component initiated the clean exit.
If using a modified build, ensure serve only returns on shutdown-signal cancellation, not on internal conditions.

Example fix

# before
api_server_config = FrontendConfig::default(); // no listener configured, task exits cleanly

# after
api_server_config = FrontendConfig { host: "0.0.0.0", port: 8000, .. }; // task has a listener to serve

Defensive patterns

Strategy: try-catch

Validate before calling

let cfg: FrontendConfig = args.to_frontend_config(handshake_address);
if !cfg.serves_any_listener() { return Err("no API listener configured; server would exit immediately"); }

Try / catch

if let Err(e) = serve_result {
    if e.to_string().contains("OpenAI server shut down unexpectedly") {
        tracing::error!("server exited cleanly without a signal — check listener config and earlier serve-task logs");
    }
    return Err(e);
}

Prevention

Validate that the frontend config binds at least one listener before starting the supervisor.
Watch the serve task's own logs for its shutdown reason.
In custom builds, ensure serve() only returns Ok on cancellation.

When it happens

Trigger: The serve task's graceful-exit path triggers without a signal: e.g. all listeners closed, a shutdown trigger inside the server fired, or code that returns `Ok` from the serve loop after a condition instead of awaiting cancellation.

Common situations: Bugs or version mismatches where the server task returns early on an empty configuration (e.g. zero API keys / no HTTP config mapping to 'nothing to serve'); port-binding code choosing graceful exit over error; custom builds modifying serve().

Related errors

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