tinyhumansai/openhuman · error

runtime python server exited before readiness handshake

Error message

runtime python server exited before readiness handshake

What it means

spawn_inner read EOF on the server's stdout before the ready line — the freshly spawned python server process died immediately (import error, missing interpreter). Distinct from a timeout: the pipe closed.

Source

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

            .context("spawning runtime python server")?;
    let stdin = child
        .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
        );
    }

View on GitHub (pinned to 7491200858)

Solutions

1. Check the drained stderr log for the crash reason
2. Re-provision the server venv
3. Verify the python interpreter resolves and runs the server entrypoint

When it happens

Trigger: Thrown at src/openhuman/runtime/python_server/server.rs:515 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.

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