stablyai/orca · error · Error

ORCA_PROBE_ENVIRONMENT_NAME is required

Error message

ORCA_PROBE_ENVIRONMENT_NAME is required

What it means

Thrown by the remote shared-control retirement probe when the ORCA_PROBE_ENVIRONMENT_NAME env var is unset. The probe resolves a runtime environment by name from the user data store and exercises its shared-control connection lifecycle, so a target environment name is mandatory.

Source

Thrown at config/scripts/remote-shared-control-retirement-probe.ts:14

import { getDefaultUserDataPath } from '../../src/cli/runtime/metadata'
import type { PairingOffer } from '../../src/shared/pairing'
import { RemoteRuntimeSharedControlConnection } from '../../src/shared/remote-runtime-shared-control-connection'
import {
  resolveEnvironment,
  resolveEnvironmentPairingOffer
} from '../../src/shared/runtime-environment-store'
import type { MemorySnapshot } from '../../src/shared/types'
import type { RuntimeStatus } from '../../src/shared/runtime-types'

async function main(): Promise<void> {
  const environmentName = process.env.ORCA_PROBE_ENVIRONMENT_NAME
  if (!environmentName) {
    throw new Error('ORCA_PROBE_ENVIRONMENT_NAME is required')
  }
  const userDataPath = getDefaultUserDataPath()
  const environment = resolveEnvironment(userDataPath, environmentName)
  const pairing = resolveEnvironmentPairingOffer(userDataPath, environment.id)
  const cycles = readProbeInteger('ORCA_PROBE_CYCLES', 10, 100)
  const concurrency = readProbeInteger('ORCA_PROBE_CONCURRENCY', 25, 200)
  const settleMs = readProbeInteger('ORCA_PROBE_SETTLE_MS', 250, 5_000)
  const cleanupTimeoutMs = readProbeInteger('ORCA_PROBE_CLEANUP_TIMEOUT_MS', 10_000, 30_000)
  const unknownResponses = new Map<string, number>()
  const originalWarn = console.warn
  console.warn = (message?: unknown, details?: unknown): void => {
    if (
      message === '[remote-runtime.shared-control] unknown response id' &&
      typeof details === 'object' &&
      details !== null
    ) {
      const responseId = String((details as { responseId?: unknown }).responseId ?? 'unknown')
      unknownResponses.set(responseId, (unknownResponses.get(responseId) ?? 0) + 1)

View on GitHub (pinned to 1136503c6a)

Solutions

1. Set ORCA_PROBE_ENVIRONMENT_NAME to a registered runtime environment name, e.g. ORCA_PROBE_ENVIRONMENT_NAME=ssh-prod.
2. Confirm the environment exists in the user data store before running (the script calls resolveEnvironment which throws separately if not found).

Example fix

// before
node --import tsx config/scripts/remote-shared-control-retirement-probe.ts
// after
ORCA_PROBE_ENVIRONMENT_NAME=ssh-prod node --import tsx config/scripts/remote-shared-control-retirement-probe.ts

const environmentName = process.env.ORCA_PROBE_ENVIRONMENT_NAME
if (!environmentName) {
  throw new Error('Set ORCA_PROBE_ENVIRONMENT_NAME to a registered runtime environment name.')
}

function isNonEmptyString(value) {
  return typeof value === 'string' && value.trim().length > 0
}

When it happens

Trigger: Invoking the probe script without setting ORCA_PROBE_ENVIRONMENT_NAME, or exporting it as an empty string. The script has no default and no CLI fallback — the env var is the sole input.

Common situations: A developer runs the probe to test connection retirement without knowing which env vars it needs, or a wrapper script forgets to pass the environment name.

Related errors

• ${name} must be an integer from 1 through ${maximum}
• ${name} must be a positive integer, received ${value}
• ORCA_ADVERTISED_URL_BENCH_ROUNDS must be even
• ${name} must be a positive integer, received ${value}
• ${name} must be a positive integer, received ${value}

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