stablyai/orca · error · Error

${name} did not emit readiness within ${startupTimeoutMs}ms:

Error message

${name} did not emit readiness within ${startupTimeoutMs}ms:
${logResult.stdout}${logResult.stderr}

What it means

Thrown by waitForReady when the deadline (Date.now() + startupTimeoutMs) elapses while the container is still running but has not produced a complete ready contract in its logs. hasCompleteReadyContract never matched: it requires 'Orca server ready\n' plus a Pairing URL/guidance line, or at least one orca_server_ready JSON object.

Source

Thrown at config/scripts/run-headless-linux-pairing-docker.mjs:297

  while (Date.now() < deadline) {
    const logResult = docker(['logs', name], { allowFailure: true })
    const stdout = `${logResult.stdout}${logResult.stderr}`
    if (hasCompleteReadyContract(stdout)) {
      return stdout
    }
    const running = docker(['inspect', '-f', '{{.State.Running}}', name], {
      allowFailure: true
    }).stdout.trim()
    if (running === 'false') {
      const containerLogs = docker(['logs', name], { allowFailure: true })
      throw new Error(
        `${name} exited before readiness:\n${containerLogs.stdout}${containerLogs.stderr}`
      )
    }
    await new Promise((resolveWait) => setTimeout(resolveWait, 100))
  }
  const logResult = docker(['logs', name], { allowFailure: true })
  throw new Error(
    `${name} did not emit readiness within ${startupTimeoutMs}ms:\n${logResult.stdout}${logResult.stderr}`
  )
}

function hasCompleteReadyContract(stdout) {
  if (
    stdout.includes('Orca server ready\n') &&
    (stdout.includes('\nPairing URL: ') || stdout.includes('\nPairing guidance: '))
  ) {
    return true
  }
  return readyJsonObjects(stdout).length > 0
}

function validateReady(logs, mode, expectedHost, options = {}) {
  if (mode === 'human') {
    assert(
      (logs.match(/^Orca server ready$/gm) ?? []).length === 1,

View on GitHub (pinned to 1136503c6a)

Solutions

Increase startupTimeoutMs passed to waitForReady.
Inspect the appended logs to see how far startup progressed and which ready line is missing.
Confirm ORCA_PAIRING_ADDRESS/ORCA_SERVE_PORT and ORCA_READY_JSON match the mode expected by hasCompleteReadyContract.
Check for stdout buffering inside the container (use line-buffered output or stdbuf).

Example fix

// before
const stdout = await waitForReady(name, startupTimeoutMs)
// after
const stdout = await waitForReady(name, startupTimeoutMs + 60_000)
// and confirm ORCA_READY_JSON=1 when expecting JSON readiness

Defensive patterns

Strategy: retry

Validate before calling

const startupTimeoutMs = Math.max(options.startupTimeoutMs ?? 60_000, 120_000)
// pass the larger value into waitForReady so slow first boots are tolerated

Type guard

function isReady(stdout) { return hasCompleteReadyContract(stdout) }

Try / catch

let stdout
try {
  stdout = await waitForReady(name, startupTimeoutMs)
} catch (err) {
  if (/did not emit readiness/.test(err.message)) {
    stdout = await waitForReady(name, startupTimeoutMs + 60_000) // one bounded retry
  } else {
    throw err
  }
}

Prevention

Size startupTimeoutMs to the worst-case cold-boot time of the AppImage.
Match ORCA_READY_JSON to the readiness mode the test expects.
Use line-buffered output inside the container so readiness lines flush promptly.

When it happens

Trigger: Container stays alive past startupTimeoutMs but the app is slow to bind, ORCA_READY_JSON mode mismatch, or readiness output is going to a stream not captured, so hasCompleteReadyContract keeps returning false.

Common situations: Slow first boot (cold AppImage extraction), startupTimeoutMs too low, app waiting on a network/address that never resolves, ORCA_PAIRING_ADDRESS misconfigured so pairing guidance is never printed, logs buffered and not flushed.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/69bc96b235ff06a6. Report an issue: GitHub.