tinyhumansai/openhuman · error

runtime python server readiness handshake timed out

Error message

runtime python server readiness handshake timed out

What it means

HANDSHAKE_TIMEOUT expired before the server printed its ready line — the process is alive but slow (cold interpreter, first-import cost) or hung during module init.

Source

Thrown at src/openhuman/runtime/python_server/server.rs:517

        .stdin
        .take()
        .context("runtime python server stdin missing")?;
    let stdout = child
        .stdout
        .take()
        .context("runtime python server stdout missing")?;
    if let Some(stderr) = child.stderr.take() {
        drain_server_stderr(stderr);
    } else {
        log::debug!("[runtime_python_server] stderr pipe missing; continuing without drain");
    }
    let mut lines = BufReader::new(stdout).lines();

    let ready_line = match tokio::time::timeout(HANDSHAKE_TIMEOUT, lines.next_line()).await {
        Ok(Ok(Some(line))) => line,
        Ok(Ok(None)) => bail!("runtime python server exited before readiness handshake"),
        Ok(Err(error)) => return Err(error).context("reading runtime python server handshake"),
        Err(_) => bail!("runtime python server readiness handshake timed out"),
    };
    let ready: ReadyLine = serde_json::from_str(&ready_line)
        .with_context(|| format!("parsing runtime python server ready line: {ready_line}"))?;
    if !ready.ready {
        bail!(
            "runtime python server failed to start: {}",
            ready.error.unwrap_or_else(|| "unknown".to_string())
        );
    }
    if ready.protocol != Some(PROTOCOL_VERSION) {
        bail!(
            "runtime python server protocol mismatch: expected {}, got {:?}",
            PROTOCOL_VERSION,
            ready.protocol
        );
    }
    log::info!(
        "[runtime_python_server] server ready backends={:?}",

View on GitHub (pinned to 7491200858)

Solutions

1. Retry the start — cold first-boot often succeeds on retry
2. Pre-warm the venv so imports are cached
3. Check for CPU/disk starvation during startup

When it happens

Trigger: Thrown at src/openhuman/runtime/python_server/server.rs:517 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.
• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

AI-assisted analysis of tinyhumansai/openhuman@7491200858 (2026-08-17). Data as JSON: /api/errors/950ebcb171dff7e4. Report an issue: GitHub.