{"record":{"id":"5efdcd7663970a57","repo":"stablyai/orca","slug":"invalid-argument-5efdcd","errorCode":"invalid_argument","errorMessage":"Omit --linear-issue on create, or pass a Linear issue identifier or URL.","messagePattern":"Omit --linear-issue on create, or pass a Linear issue identifier or URL\\.","errorType":"exception","errorClass":"RuntimeClientError","httpStatus":null,"severity":"error","filePath":"src/cli/handlers/worktree-linear-issue-link.ts","lineNumber":20,"sourceCode":"  buildLinearIssueLinkUpdates,\n  LINEAR_ISSUE_LINK_CLEARED,\n  type LinearIssueLinkUpdates\n} from '../../shared/linear-links'\nimport { RuntimeClientError } from '../runtime-client'\n\nexport function getOptionalLinearIssueLinkFlag(\n  flags: Map<string, string | boolean>,\n  name: string,\n  options: { allowNull?: boolean } = {}\n): LinearIssueLinkUpdates | undefined {\n  const value = getPresentStringFlag(flags, name)\n  if (value === undefined) {\n    return undefined\n  }\n\n  if (value.trim().toLowerCase() === 'null') {\n    if (!options.allowNull) {\n      throw new RuntimeClientError(\n        'invalid_argument',\n        'Omit --linear-issue on create, or pass a Linear issue identifier or URL.'\n      )\n    }\n    return { ...LINEAR_ISSUE_LINK_CLEARED }\n  }\n\n  // Why: the shared builder treats empty input as \"clear\", which is right for a\n  // text field the user can blank but wrong for a flag — `--linear-issue \"  \"`\n  // is a mistyped argument, not a request to unlink. Only the literal `null`\n  // clears, and that is handled above.\n  const updates = value.trim() === '' ? null : buildLinearIssueLinkUpdates(value)\n  if (!updates) {\n    throw new RuntimeClientError(\n      'invalid_argument',\n      'Pass a Linear issue identifier like STA-335, a Linear issue URL, or null to clear.'\n    )\n  }","sourceCodeStart":2,"sourceCodeEnd":38,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/cli/handlers/worktree-linear-issue-link.ts#L2-L38","documentation":"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.","triggerScenarios":"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.","commonSituations":"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'.","solutions":["Omit --linear-issue entirely on create when you do not want to link an issue.","Pass a real Linear identifier (e.g. --linear-issue STA-335) or a Linear issue URL.","In shared scripts, only append '--linear-issue null' on the update branch, never the create branch."],"exampleFix":"# before\norca worktree create --linear-issue null\n# after\norca worktree create","handlingStrategy":"validation","validationCode":"// Before calling getOptionalLinearIssueLinkFlag on the create path:\nconst raw = flags.get('linear-issue');\nif (typeof raw === 'string' && raw.trim().toLowerCase() === 'null' && !options?.allowNull) {\n  // Skip the flag instead of passing 'null' through\n  flags.delete('linear-issue');\n}","typeGuard":"function isClearSentinel(value: string): boolean {\n  return value.trim().toLowerCase() === 'null';\n}","tryCatchPattern":"try {\n  const link = getOptionalLinearIssueLinkFlag(flags, 'linear-issue', { allowNull: isUpdate });\n} catch (e) {\n  if (e instanceof RuntimeClientError && e.code === 'invalid_argument') {\n    console.error(e.message);\n    process.exit(1);\n  }\n  throw e;\n}","preventionTips":["Separate flag templates for create vs update paths in scripts.","Only include --linear-issue when you have a real identifier or URL.","Treat the literal 'null' as a deliberate clear-sentinel, not a default."],"tags":["cli","linear","worktree","flag-validation","create"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}