stablyai/orca · error · RuntimeClientError

invalid_argument

invalid_argument

Error message

Missing required --${name}

What it means

Thrown by getRequiredStringFlag (environment.ts) when a required string flag is missing or empty. The local copy mirrors the shared helper in flags.ts: it reads flags.get(name) and rejects anything that is not a non-empty string. environment.ts uses this for flags the runtime cannot proceed without (e.g. an environment id or name).

Solutions

1. Check the command's usage to see which flags are required, then supply the missing --<name> with a non-empty value.
2. If using a shell variable, verify it is set and non-empty before passing it: --id "$ENV_ID" where ENV_ID is exported.
3. Ensure there is no leading/trailing whitespace or quote artifact making the value effectively empty.

Example fix

// before
orca environment remove
// after
orca environment remove --id env_abc123

function requireStringFlag(flags: Map<string, string | boolean>, name: string): string {
  const v = flags.get(name);
  if (typeof v === 'string' && v.length > 0) return v;
  throw new Error(`Missing required --${name}`);
}

function hasNonEmptyStringFlag(flags: Map<string, string | boolean>, name: string): boolean {
  const v = flags.get(name);
  return typeof v === 'string' && v.length > 0;
}

When it happens

Trigger: Calling an environment subcommand (create/remove/use) without a required flag such as --id or --name, or passing the flag with an empty value (--id ""). The exact flag name appears in the message via --${name}.

Common situations: Forgetting the identifier flag when scripting environment operations; passing an env var that expanded to empty; typo in the flag name so the intended value lands under a different key.

Understand the failure class

Background: "must be a positive integer", "cannot be empty", "invalid argument": how invalid-argument errors work across open-source libraries — this error's family across 33 libraries.

Related errors

• requires a path
• --baseline requires a path
• --candidate requires a path
• invalid_argument
• invalid_argument

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

Appendix: source

Thrown at src/cli/handlers/environment.ts:60

      formatEnvironment(value)
    )
  },
  'environment rm': async ({ flags, json }) => {
    const selector = getRequiredStringFlag(flags, 'environment')
    const removed = redactRuntimeEnvironment(removeEnvironment(getDefaultUserDataPath(), selector))
    printResult(
      localSuccess({ removed }),
      json,
      (result: EnvironmentRemoveResult) =>
        `Removed environment ${result.removed.name} (${result.removed.id}).`
    )
  }
}

function getRequiredStringFlag(flags: Map<string, string | boolean>, name: string): string {
  const value = flags.get(name)
  if (typeof value !== 'string' || value.length === 0) {
    throw new RuntimeClientError('invalid_argument', `Missing required --${name}`)
  }
  return value
}

function localSuccess<TResult>(result: TResult): RuntimeRpcSuccess<TResult> {
  return {
    id: 'local',
    ok: true,
    result,
    _meta: {
      runtimeId: 'local'
    }
  }
}

View on GitHub (pinned to 1136503c6a)