{"record":{"id":"d33e05abe56f7f3c","repo":"jackwener/OpenCLI","slug":"label-accepts-exactly-one-reference","errorCode":null,"errorMessage":"${label} accepts exactly one reference","messagePattern":"(.+?) accepts exactly one reference","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"clis/midjourney/utils.js","lineNumber":878,"sourceCode":"}\n\nexport function parseReferenceArgument(value, label, { multiple = true, allowStyleCode = false } = {}) {\n  if (value == null || value === '') return [];\n  let items;\n  const raw = String(value).trim();\n  if (raw.startsWith('[')) {\n    try {\n      items = JSON.parse(raw);\n    } catch (error) {\n      throw new ArgumentError(`${label} must be a path/URL or a JSON array: ${errorMessage(error)}`);\n    }\n  } else {\n    items = [raw];\n  }\n  if (!Array.isArray(items) || items.length === 0 || items.some((item) => typeof item !== 'string' || !item.trim())) {\n    throw new ArgumentError(`${label} must contain one or more non-empty strings`);\n  }\n  if (!multiple && items.length !== 1) throw new ArgumentError(`${label} accepts exactly one reference`);\n  return items.map((item) => item.trim()).map((item) => {\n    if (allowStyleCode && /^\\d+$/.test(item)) return { kind: 'styleCode', value: item };\n    if (/^https:\\/\\//i.test(item)) {\n      try {\n        const parsed = new URL(item);\n        const match = parsed.hostname === MIDJOURNEY_DOMAIN\n          ? parsed.pathname.match(/^\\/jobs\\/([0-9a-f-]{36})\\/?$/i)\n          : null;\n        if (match && UUID_RE.test(match[1])) {\n          const index = Number(parsed.searchParams.get('index') || 0);\n          if (!Number.isInteger(index) || index < 0 || index > 3) {\n            throw new ArgumentError(`${label} Midjourney job URL index must be 0..3: ${item}`);\n          }\n          return { kind: 'url', value: originalImageUrl(match[1].toLowerCase(), index), source: item };\n        }\n      } catch (error) {\n        if (error instanceof ArgumentError) throw error;\n      }","sourceCodeStart":860,"sourceCodeEnd":896,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/midjourney/utils.js#L860-L896","documentation":"When the multiple option is disabled, the reference parser enforces that exactly one reference was supplied. If the resolved list contains more than one item, this ArgumentError is thrown, because the command consuming the reference only supports a single input.","triggerScenarios":"Calling without the multiple flag/option while passing a JSON array with 2+ items (e.g. '[\"a.png\",\"b.png\"]') for a single-reference parameter.","commonSituations":"Scripts written for multi-reference commands reused on single-reference flags, users assuming flags accept lists by default, or copy-pasted multi-image examples run against a single-image argument.","solutions":["Pass exactly one reference, e.g. --refs './cat.png'","Enable the multiple option/flag if several references are genuinely supported for that argument","Split the work into multiple invocations, one reference per call"],"exampleFix":"// before\nparseReferences('refs', '[\"a.png\",\"b.png\"]', { multiple: false });\n// after\nparseReferences('refs', '[\"a.png\",\"b.png\"]', { multiple: true });\n// or single:\nparseReferences('refs', 'a.png', { multiple: false });","handlingStrategy":"validation","validationCode":"if (!multiple && parsedItems.length !== 1) {\n  throw new Error('this argument accepts exactly one reference; pass multiple: true for lists');\n}","typeGuard":"const isSingleRef = (v) => typeof v === 'string' || (Array.isArray(v) && v.length === 1);","tryCatchPattern":"try {\n  const refs = parseReferences('refs', raw, { multiple: false });\n} catch (e) {\n  if (String(e.message).includes('accepts exactly one reference')) {\n    console.error('Pass a single reference or enable multiple mode');\n  }\n  throw e;\n}","preventionTips":["Check whether the argument supports multiple references before passing arrays","Default scripts to one reference per invocation","Keep separate flag names/paths for single vs batch workflows"],"tags":["argument-validation","cli","arity-mismatch"],"backgroundTag":"invalid-argument-input","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}