stablyai/orca · error · RuntimeClientError

invalid_environment

invalid_environment

Error message

orca claude-teams must be run inside an Orca terminal.

What it means

The claude-teams handler (core.ts:70) requires the ORCA_PANE_KEY environment variable, which Orca exports only inside its own managed terminal panes. The variable identifies the pane to agentTeams.prepareLaunch; without it the command has no pane context and throws invalid_environment before the RPC.

Source

Thrown at src/cli/handlers/core.ts:70

  }
  const port = Number(rawPort)
  if (!Number.isInteger(port) || port < 0 || port > 65535) {
    throw new RuntimeClientError('invalid_argument', `Invalid --port value: ${rawPort}`)
  }
  return rawPort
}

export const CORE_HANDLERS: Record<string, CommandHandler> = {
  'claude-teams': async ({ client, rawArgs }) => {
    if (process.platform === 'win32') {
      throw new RuntimeClientError(
        'unsupported_platform',
        'Claude Agent Teams native panes are not supported on Windows.'
      )
    }
    const paneKey = process.env.ORCA_PANE_KEY
    if (!paneKey) {
      throw new RuntimeClientError(
        'invalid_environment',
        'orca claude-teams must be run inside an Orca terminal.'
      )
    }
    const response = await client.call<{ launch: { env: Record<string, string> } }>(
      'agentTeams.prepareLaunch',
      {
        paneKey,
        env: envRecord()
      }
    )
    process.exitCode = await runClaudeAgentTeams(
      {
        ...envRecord(),
        ...response.result.launch.env
      },
      rawArgs ?? []
    )

View on GitHub (pinned to 1136503c6a)

Solutions

Run the command inside an Orca terminal pane, which sets ORCA_PANE_KEY automatically
If scripting within an existing pane, ensure ORCA_PANE_KEY is preserved (do not env-scrub it)
For remote/SSH use, connect through Orca's remote session so the pane env is present

Defensive patterns

Strategy: validation

Validate before calling

function assertInsideOrcaPane() {
  if (!process.env.ORCA_PANE_KEY) {
    throw new Error('orca claude-teams must be run inside an Orca terminal')
  }
}

Prevention

Only invoke claude-teams from within an Orca pane that exports ORCA_PANE_KEY
Do not sanitize env in wrapper scripts in a way that drops ORCA_PANE_KEY
For remote use, connect through Orca's remote session so the pane env is present

When it happens

Trigger: Running `orca claude-teams ...` from a system terminal, an editor's integrated terminal, or an SSH session that is not an Orca pane (ORCA_PANE_KEY unset).

Common situations: Testing the subcommand from a plain shell; SSH-ing into a remote that is not the Orca host; a wrapper that sanitizes env and dropped ORCA_PANE_KEY; running inside a container without the Orca pane env.

Related errors

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