stablyai/orca · error · RuntimeClientError

linear_invalid_write_id

linear_invalid_write_id

Error message

--write-id must be a UUID

What it means

Thrown by getOptionalWriteId when `--write-id` is present but not a valid Linear UUID. The write-id is the idempotency/dedup key for a Linear write, and Linear rejects non-UUID identifiers; this guard fails fast in the CLI with a stable error code instead of surfacing an opaque API rejection later.

Source

Thrown at src/cli/linear-request-builders.ts:207

  }
}

export function rejectAllWorkspaceForWrite(flags: Map<string, string | boolean>): void {
  if (getOptionalStringFlag(flags, 'workspace') === 'all') {
    throw new RuntimeClientError(
      'linear_invalid_workspace',
      '--workspace all is not valid for Linear writes'
    )
  }
}

export function getOptionalWriteId(flags: Map<string, string | boolean>): string | undefined {
  if (!flags.has('write-id')) {
    return undefined
  }
  const writeId = getRequiredStringFlag(flags, 'write-id')
  if (!isLinearUuid(writeId)) {
    throw new RuntimeClientError('linear_invalid_write_id', '--write-id must be a UUID')
  }
  return writeId
}

export function getHttpUrlFlag(flags: Map<string, string | boolean>, name: string): string {
  const value = getRequiredStringFlag(flags, name)
  try {
    const parsed = new URL(value)
    if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
      return value
    }
  } catch {
    // Fall through to the stable Linear error below.
  }
  throw new RuntimeClientError('linear_invalid_url', '--url must be an absolute http(s) URL')
}

export function readLinearBody(

View on GitHub (pinned to 1136503c6a)

Solutions

1. Generate a proper UUID: `--write-id $(uuidgen)` (macOS/Linux) or `--write-id $(powershell -c [guid]::NewGuid())` (Windows).
2. If you have an existing write-id, copy the full UUID string without trimming.
3. Omit `--write-id` entirely if you do not need idempotency/dedup on this write.

Example fix

// before
linear comment LIN-123 --write-id LIN-123 --body "..."
// after
linear comment LIN-123 --write-id $(uuidgen) --body "..."

import { randomUUID } from 'node:crypto'
const writeId = flags.get('write-id') ?? randomUUID()
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
if (!UUID_RE.test(writeId)) throw new Error('write-id must be a UUID')

function isLinearUuid(value: string): boolean {
  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)
}

When it happens

Trigger: Passing `--write-id` with anything that is not a UUID (e.g. `--write-id LIN-123`, `--write-id 123`, a truncated/partial UUID). The isLinearUuid regex/format check fails.

Common situations: Confusing the Linear issue identifier (LIN-123) with the write-id. Hand-typing or copy-truncating a UUID. Reusing an issue UUID as a write-id when one is needed. Forgetting to generate a fresh UUID per write attempt and reusing a stale string.

Related errors

• invalid_argument
• invalid_argument
• linear_invalid_workspace
• linear_issue_required
• linear_invalid_url

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