stablyai/orca · error · RuntimeClientError

invalid_argument

invalid_argument

Error message

Missing value for --worktree.

What it means

Thrown by getFileWorktreeSelector in file.ts when --worktree is present but has no usable string value. The check is `flags.has('worktree') && (typeof worktree !== 'string' || worktree.length === 0)`: the flag was explicitly passed but is empty or boolean-only. File commands need a worktree selector to scope file operations, so an explicitly empty value is invalid_argument.

Source

Thrown at src/cli/handlers/file.ts:34

  staged?: boolean
  opened: boolean
  kind?: RuntimeFileOpenResult['kind']
  skipped?: boolean
  reason?: string
}

type FileOpenChangedResult = {
  worktree: string
  mode: OpenChangedMode
  opened: FileOpenRecord[]
  skipped: FileOpenRecord[]
  totalChanged: number
}

async function getFileWorktreeSelector({ flags, cwd, client }: HandlerContext): Promise<string> {
  const worktree = flags.get('worktree')
  if (flags.has('worktree') && (typeof worktree !== 'string' || worktree.length === 0)) {
    throw new RuntimeClientError('invalid_argument', 'Missing value for --worktree.')
  }
  const explicit = await getOptionalWorktreeSelector(flags, 'worktree', cwd, client)
  if (explicit) {
    return explicit
  }
  if (client.isRemote) {
    throw new RuntimeClientError(
      'invalid_argument',
      'Remote file commands require --worktree because the client cwd cannot identify a server worktree.'
    )
  }
  return await resolveCurrentWorktreeSelector(cwd, client)
}

async function resolveFilePath(
  ctx: HandlerContext,
  worktree: string,
  path: string

View on GitHub (pinned to 1136503c6a)

Solutions

1. Either omit --worktree entirely (so the CLI resolves the current worktree), or pass a non-empty selector value.
2. If the value comes from a variable, guard the script to only add --worktree when the variable is non-empty.
3. Verify the worktree path/id is correct and not accidentally truncated.

Example fix

// before
orca file open-changed --worktree
// after
orca file open-changed --worktree main
// or omit it to use the current worktree
orca file open-changed

function resolveWorktreeFlag(flags: Map<string, string | boolean>): string | undefined {
  if (!flags.has('worktree')) return undefined;
  const v = flags.get('worktree');
  if (typeof v === 'string' && v.length > 0) return v;
  throw new Error('--worktree was passed but is empty; omit it or supply a value');
}

When it happens

Trigger: Passing `--worktree` with no value, or `--worktree ""` (empty string), or `--worktree=` on the command line. The flag's presence triggers the emptiness check.

Common situations: Shell variable that is unset expanding to an empty string; a script that conditionally adds --worktree but passes an empty value; typo where the value goes to the next flag.

Related errors

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

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