{"record":{"id":"2e0893b2e5179d54","repo":"stablyai/orca","slug":"linear-invalid-write-id","errorCode":"linear_invalid_write_id","errorMessage":"--write-id must be a UUID","messagePattern":"--write-id must be a UUID","errorType":"validation","errorClass":"RuntimeClientError","httpStatus":null,"severity":"error","filePath":"src/cli/linear-request-builders.ts","lineNumber":207,"sourceCode":"  }\n}\n\nexport function rejectAllWorkspaceForWrite(flags: Map<string, string | boolean>): void {\n  if (getOptionalStringFlag(flags, 'workspace') === 'all') {\n    throw new RuntimeClientError(\n      'linear_invalid_workspace',\n      '--workspace all is not valid for Linear writes'\n    )\n  }\n}\n\nexport function getOptionalWriteId(flags: Map<string, string | boolean>): string | undefined {\n  if (!flags.has('write-id')) {\n    return undefined\n  }\n  const writeId = getRequiredStringFlag(flags, 'write-id')\n  if (!isLinearUuid(writeId)) {\n    throw new RuntimeClientError('linear_invalid_write_id', '--write-id must be a UUID')\n  }\n  return writeId\n}\n\nexport function getHttpUrlFlag(flags: Map<string, string | boolean>, name: string): string {\n  const value = getRequiredStringFlag(flags, name)\n  try {\n    const parsed = new URL(value)\n    if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {\n      return value\n    }\n  } catch {\n    // Fall through to the stable Linear error below.\n  }\n  throw new RuntimeClientError('linear_invalid_url', '--url must be an absolute http(s) URL')\n}\n\nexport function readLinearBody(","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/cli/linear-request-builders.ts#L189-L225","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Generate a proper UUID: `--write-id $(uuidgen)` (macOS/Linux) or `--write-id $(powershell -c [guid]::NewGuid())` (Windows).","If you have an existing write-id, copy the full UUID string without trimming.","Omit `--write-id` entirely if you do not need idempotency/dedup on this write."],"exampleFix":"// before\nlinear comment LIN-123 --write-id LIN-123 --body \"...\"\n// after\nlinear comment LIN-123 --write-id $(uuidgen) --body \"...\"","handlingStrategy":"type-guard","validationCode":"import { randomUUID } from 'node:crypto'\nconst writeId = flags.get('write-id') ?? randomUUID()\nconst UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i\nif (!UUID_RE.test(writeId)) throw new Error('write-id must be a UUID')","typeGuard":"function isLinearUuid(value: string): boolean {\n  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)\n}","tryCatchPattern":null,"preventionTips":["Always generate write-ids with a UUID generator (uuidgen / crypto.randomUUID).","Never reuse a Linear issue identifier as a write-id."],"tags":["linear","cli","flag-validation","uuid","idempotency"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}