tinyhumansai/openhuman · error

{} worker readiness handshake timed out

Error message

{} worker readiness handshake timed out

What it means

HANDSHAKE_TIMEOUT elapsed before the worker emitted its first stdout line: the process is alive but slow to start (cold interpreter boot, first-run venv setup) or hung. Distinct from EOF, which would mean the worker exited.

Source

Thrown at src/openhuman/runtime/pool/worker.rs:179

        } else {
            (
                Box::new(child_stdin.context("worker stdin missing")?),
                Box::new(stdout),
                None,
            )
        };
        let mut lines = BufReader::new(reader).lines();

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

View on GitHub (pinned to 7491200858)

Solutions

1. Retry the launch — cold starts often pass on a second attempt
2. Check for CPU starvation or a hung dependency import in the worker
3. Increase the handshake timeout if the environment is consistently slow

When it happens

Trigger: Thrown at src/openhuman/runtime/pool/worker.rs:179 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/b3a4964396d60216. Report an issue: GitHub.