stablyai/orca · error · Error

Missing helper process record path

Error message

Missing helper process record path

What it means

startAuthenticatedSession expects the helper process record path via an env var (HELPER_RECORD_PATH_ENV). After the helper appears it writes the helper's pid/socket info to that path so sibling processes (e.g. the invalid-peer probe) can locate the helper. If the env var is unset, the orchestration cannot publish the record and aborts before the capabilities check.

Source

Thrown at config/scripts/macos-computer-helper-owner-loss-benchmark.mjs:268

  }
  return await Promise.race([
    new Promise((resolve) => child.once('exit', () => resolve(true))),
    sleep(timeoutMs).then(() => false)
  ])
}

async function startAuthenticatedSession() {
  const sidecar = startSidecar()
  let helper
  try {
    const capabilitiesResult = requestSidecar(sidecar, 1, 'capabilities').then(
      (capabilities) => ({ capabilities }),
      (error) => ({ error })
    )
    helper = await waitForHelper(sidecar.child.pid)
    const helperRecordPath = process.env[HELPER_RECORD_PATH_ENV]
    if (!helperRecordPath) {
      throw new Error('Missing helper process record path')
    }
    writeProcessRecord(helperRecordPath, helper)
    const { capabilities, error } = await capabilitiesResult
    if (error) {
      throw error
    }
    if (capabilities?.protocolVersion !== 1) {
      throw new Error(`Unexpected helper handshake: ${JSON.stringify(capabilities)}`)
    }
    return { authenticated: capabilities.protocolVersion === 1, sidecar, helper }
  } catch (error) {
    sidecar.child.kill('SIGKILL')
    await stopProcess(helper)
    throw error
  }
}

async function exerciseActiveRequests(sidecar) {

View on GitHub (pinned to 1136503c6a)

Solutions

1. Export HELPER_RECORD_PATH_ENV (the actual constant's name) pointing at a writable temp file before running the script.
2. Run the benchmark via the harness/runner that normally configures it rather than invoking the .mjs directly.
3. If the var was renamed, update all call sites to the new name.

Example fix

# before
node config/scripts/macos-computer-helper-owner-loss-benchmark.mjs

# after
HELPER_RECORD_PATH=/tmp/helper-record.json node config/scripts/macos-computer-helper-owner-loss-benchmark.mjs

const recordPath = process.env[HELPER_RECORD_PATH_ENV]
if (!recordPath) {
  throw new Error(`${HELPER_RECORD_PATH_ENV} must be set to a writable path before running the benchmark`)
}

const isSetEnv = (name) => typeof process.env[name] === 'string' && process.env[name].length > 0

When it happens

Trigger: Running the benchmark script (or its startAuthenticatedSession path) without the HELPER_RECORD_PATH_ENV environment variable exported — typically a harness/CI integration that forgot to set it.

Common situations: Invoking the script directly during debugging instead of through the harness that configures the env, a CI template that dropped the var, or a rename of the env var name that left callers setting the old name.

Related errors

• Unsupported boundary: ${boundary}
• Invalid ${name}: expected a finite number, got ${JSON.string
• Unknown ORCA_FREEZE_SCENARIO=${scenario}. Expected one of: $
• Could not find helper owned by sidecar ${sidecarPid}
• ${name} must be a positive integer, received ${value}

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