stablyai/orca · error · RuntimeClientError

invalid_argument

invalid_argument

Error message

Missing required ${name}.

What it means

Thrown by requireStringFlag() in the artifacts CLI handler when a required string flag is absent, empty, or whitespace-only. stringFlag() returns undefined unless ctx.flags.get(name) is a non-empty trimmed string, so any falsy/blank value trips the guard. The message interpolates the offending flag name (e.g. 'file' or 'id'). It is a client-side invalid_argument error raised before any RPC is attempted.

Source

Thrown at src/cli/handlers/artifacts.ts:33

import {
  ARTIFACT_SHARING_DISABLED_CODE,
  ARTIFACT_SHARING_DISABLED_MESSAGE,
  ARTIFACT_SHARING_DISABLED_NEXT_STEPS
} from '../../shared/artifact-sharing-gate'
import type { CommandHandler, HandlerContext } from '../dispatch'
import { RuntimeClientError } from '../runtime-client'
import { formatArtifactListPage, formatArtifactShared } from '../artifact-format'
import { printResult } from '../format'

function stringFlag(ctx: HandlerContext, name: string): string | undefined {
  const value = ctx.flags.get(name)
  return typeof value === 'string' && value.trim() ? value.trim() : undefined
}

function requireStringFlag(ctx: HandlerContext, name: string): string {
  const value = stringFlag(ctx, name)
  if (!value) {
    throw new RuntimeClientError('invalid_argument', `Missing required ${name}.`)
  }
  return value
}

function cloudOptions(ctx: HandlerContext): ArtifactCloudOptions {
  const apiUrl = stringFlag(ctx, 'api-url') ?? process.env.ORCA_ARTIFACTS_API_URL?.trim()
  const authToken = process.env.ORCA_CLOUD_AUTH_TOKEN?.trim()
  return {
    ...(apiUrl ? { apiUrl } : {}),
    ...(authToken ? { authToken } : {})
  }
}

function rejectRemoteSelectionFlags(ctx: HandlerContext): void {
  for (const flag of ['environment', 'pairing-code']) {
    if (ctx.flags.has(flag)) {
      throw new RuntimeClientError(
        'invalid_argument',

View on GitHub (pinned to 1136503c6a)

Solutions

1. Re-run the command with the missing flag, e.g. `orca artifacts share --file ./report.html` or `orca artifacts delete --id <artifact-id>`.
2. If scripting, check the flag is a non-empty string before invoking: guard `if [ -n "$FILE" ]` in shell, or validate the value in TS before building the HandlerContext.
3. Confirm you are not passing `--file` with an empty quoted value; remove the flag entirely rather than blanking it.
4. For remote/bridged runs, set the REMOTE_ARTIFACT_INPUT_ENV env var so sourceKey is taken from there instead of --file (unshare path).

Example fix

// before
orca artifacts share   // ERROR: Missing required file.

// after
orca artifacts share --file ./out/report.html

function buildArtifactsArgs(flags: Record<string, string|boolean>, require: ('file'|'id')[]) {
  for (const name of require) {
    const v = flags[name]
    if (typeof v !== 'string' || v.trim().length === 0) {
      throw new Error(`Missing required --${name}`)
    }
  }
}
// call before dispatching 'artifacts share/update/unshare' (need --file) or 'artifacts delete' (need --id)

const isNonEmptyString = (v: unknown): v is string =>
  typeof v === 'string' && v.trim().length > 0

try {
  await dispatch('artifacts share', ctx)
} catch (e) {
  if (e instanceof RuntimeClientError && e.code === 'invalid_argument' && /Missing required/.test(e.message)) {
    // surface to the user which flag is missing (name is in the message)
  }
  throw e
}

When it happens

Trigger: Invoking `orca artifacts share` or `orca artifacts update` without `--file`; `orca artifacts delete` without `--id`; `orca artifacts unshare` without `--file` and without a REMOTE_ARTIFACT_INPUT_ENV override. Also fires when the flag is present but blank (e.g. `--file ''`) or set to a boolean true with no value.

Common situations: Forgetting the positional/flag argument after copy-pasting a command from docs that used a placeholder; shell quoting that swallows the value (`--file=$EMPTY`); scripts that conditionally omit the flag; piping assumptions where the user expects stdin to substitute for --file (it does not for the local path branch).

Related errors

• invalid_argument
• --baseline requires a path
• --candidate requires a path
• --title requires a value
• --output requires a path

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