stablyai/orca · error · RuntimeClientError

invalid_argument

invalid_argument

Error message

Use either --pairing-code or --environment, not both.

What it means

Thrown by resolveRemotePairing when BOTH `--pairing-code` and `--environment` are supplied. Remote pairing resolves a target via exactly one channel: an explicit pairing code (orca://pair URL or bare payload) or a named environment selector. Providing both is ambiguous and the builder refuses to pick.

Source

Thrown at src/cli/runtime/client.ts:277

      orchestrationRequestId: requestId
    }
  )
}

function throwDesktopActivationBlocked(): never {
  throw new RuntimeClientError(
    'desktop_activation_blocked',
    'Orca is running headlessly, but it cannot open a desktop window safely because the persistent terminal provider is unavailable. Quit Orca normally and start the app again; do not use open -n.'
  )
}

function resolveRemotePairing(
  userDataPath: string,
  pairingCode: string | null,
  environmentSelector: string | null
): PairingOffer | null {
  if (pairingCode && environmentSelector) {
    throw new RuntimeClientError(
      'invalid_argument',
      'Use either --pairing-code or --environment, not both.'
    )
  }
  if (environmentSelector) {
    return resolveEnvironmentPairingOffer(userDataPath, environmentSelector)
  }
  if (!pairingCode) {
    return null
  }
  const pairing = parsePairingCode(pairingCode)
  if (!pairing) {
    throw new RuntimeClientError(
      'invalid_argument',
      'Invalid remote pairing code. Expected an orca://pair?... URL or bare pairing payload.'
    )
  }
  return pairing

View on GitHub (pinned to 1136503c6a)

Solutions

1. Keep `--pairing-code <code>` and remove `--environment` for direct pairing.
2. Or keep `--environment <name>` and remove `--pairing-code` to pair via the named environment.
3. Audit config files and aliases that may inject both flags.

Example fix

// before
orca remote --pairing-code orca://pair?c=abc --environment prod
// after
orca remote --pairing-code orca://pair?c=abc

if (pairingCode && environmentSelector) {
  throw new Error('Pass either --pairing-code or --environment, not both')
}

function hasSinglePairingChannel(code: string | null, env: string | null): boolean {
  return Boolean(code) !== Boolean(env)
}

When it happens

Trigger: Invoking a remote-pairing command with both flags set, e.g. `--pairing-code orca://pair?... --environment prod`. Any call into resolveRemotePairing where both pairingCode and environmentSelector are non-null.

Common situations: Scripts that set a default `--environment` and then pass `--pairing-code` for one run. Migrating from environment-selector-based to code-based pairing and forgetting to clear the old flag. Config files that populate both.

Related errors

• invalid_argument
• invalid_argument
• invalid_argument
• invalid_argument
• invalid_argument

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