stablyai/orca · error · RuntimeClientError

invalid_argument

invalid_argument

Error message

Omit --linear-issue on create, or pass a Linear issue identifier or URL.

What it means

Thrown by getOptionalLinearIssueLinkFlag when the user passes the literal string 'null' as the --linear-issue value on a code path where allowNull is not enabled (i.e., worktree create). On create there is no existing link to clear, so 'null' is meaningless. The literal is intercepted before the parser so an issue whose team prefix happens to be 'null' is not confused with the clear sentinel.

Source

Thrown at src/cli/handlers/worktree-linear-issue-link.ts:20

  buildLinearIssueLinkUpdates,
  LINEAR_ISSUE_LINK_CLEARED,
  type LinearIssueLinkUpdates
} from '../../shared/linear-links'
import { RuntimeClientError } from '../runtime-client'

export function getOptionalLinearIssueLinkFlag(
  flags: Map<string, string | boolean>,
  name: string,
  options: { allowNull?: boolean } = {}
): LinearIssueLinkUpdates | undefined {
  const value = getPresentStringFlag(flags, name)
  if (value === undefined) {
    return undefined
  }

  if (value.trim().toLowerCase() === 'null') {
    if (!options.allowNull) {
      throw new RuntimeClientError(
        'invalid_argument',
        'Omit --linear-issue on create, or pass a Linear issue identifier or URL.'
      )
    }
    return { ...LINEAR_ISSUE_LINK_CLEARED }
  }

  // Why: the shared builder treats empty input as "clear", which is right for a
  // text field the user can blank but wrong for a flag — `--linear-issue "  "`
  // is a mistyped argument, not a request to unlink. Only the literal `null`
  // clears, and that is handled above.
  const updates = value.trim() === '' ? null : buildLinearIssueLinkUpdates(value)
  if (!updates) {
    throw new RuntimeClientError(
      'invalid_argument',
      'Pass a Linear issue identifier like STA-335, a Linear issue URL, or null to clear.'
    )
  }

View on GitHub (pinned to 1136503c6a)

Solutions

1. Omit --linear-issue entirely on create when you do not want to link an issue.
2. Pass a real Linear identifier (e.g. --linear-issue STA-335) or a Linear issue URL.
3. In shared scripts, only append '--linear-issue null' on the update branch, never the create branch.

Example fix

# before
orca worktree create --linear-issue null
# after
orca worktree create

// Before calling getOptionalLinearIssueLinkFlag on the create path:
const raw = flags.get('linear-issue');
if (typeof raw === 'string' && raw.trim().toLowerCase() === 'null' && !options?.allowNull) {
  // Skip the flag instead of passing 'null' through
  flags.delete('linear-issue');
}

function isClearSentinel(value: string): boolean {
  return value.trim().toLowerCase() === 'null';
}

try {
  const link = getOptionalLinearIssueLinkFlag(flags, 'linear-issue', { allowNull: isUpdate });
} catch (e) {
  if (e instanceof RuntimeClientError && e.code === 'invalid_argument') {
    console.error(e.message);
    process.exit(1);
  }
  throw e;
}

When it happens

Trigger: Running 'orca worktree create --linear-issue null' (or with surrounding whitespace like '--linear-issue " null "'). The allowNull option defaults to false; only the update path sets it to true.

Common situations: User copies an update-style command template that includes '--linear-issue null' into a create invocation. CI scripts that reuse the same flag set for both create and update. User types 'null' meaning 'no issue, please'.

Related errors

• invalid_argument
• invalid_argument
• linear_invalid_workspace
• linear_issue_required
• linear_invalid_write_id

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