{"record":{"id":"d380f4adf354852e","repo":"affaan-m/ECC","slug":"invalid-metadata-json-error-message","errorCode":null,"errorMessage":"Invalid --metadata-json: ${error.message}","messagePattern":"Invalid --metadata-json: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/work-items.js","lineNumber":129,"sourceCode":"    } else if (!arg.startsWith('-')) {\n      parsed.positionals.push(arg);\n    } else {\n      throw new Error(`Unknown argument: ${arg}`);\n    }\n  }\n\n  return parsed;\n}\n\nfunction parseMetadataJson(value) {\n  if (value === undefined || value === null) {\n    return null;\n  }\n\n  try {\n    return JSON.parse(value);\n  } catch (error) {\n    throw new Error(`Invalid --metadata-json: ${error.message}`);\n  }\n}\n\nfunction resolveWorkItemId(options) {\n  return options.id || options.positionals[0] || null;\n}\n\nfunction normalizeLimit(value) {\n  const parsed = Number.parseInt(value, 10);\n  if (!Number.isFinite(parsed) || parsed <= 0) {\n    throw new Error(`Invalid limit: ${value}`);\n  }\n  return parsed;\n}\n\nfunction runGhJson(args) {\n  const shimPath = process.env.ECC_GH_SHIM;\n  const command = shimPath ? process.execPath : 'gh';","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/affaan-m/ECC/blob/01e15490f04e29cfefe3896951f43db46994d8ee/scripts/work-items.js#L111-L147","documentation":"Thrown by scripts/parseMetadataJson in scripts/work-items.js when the --metadata-json value fails JSON.parse. The metadata field is stored as structured JSON on the work item, so the CLI requires a valid JSON string literal on the command line. The original parse error message is included to pinpoint the syntax problem (e.g. unexpected token, unterminated string).","triggerScenarios":"`node scripts/work-items.js upsert --title X --metadata-json \"{bad}\"` (invalid JSON); passing a bare key=value string instead of a JSON object; unbalanced braces or missing quotes around keys.","commonSituations":"Single-quoting a JSON string in the shell but forgetting inner quotes; passing YAML or key=value by mistake; a wrapper script building the JSON by string concatenation that produces invalid syntax when a field is null.","solutions":["Validate the JSON with a linter or `echo '<json>' | jq .` before passing it.","Use single quotes around a double-quoted JSON object in the shell: `--metadata-json '{\"key\":\"value\"}'`.","If building the string programmatically, use JSON.stringify on a real object rather than hand-concatenating."],"exampleFix":"// before\nnode scripts/work-items.js upsert --title X --metadata-json \"{bad}\"\n\n// after\nnode scripts/work-items.js upsert --title X --metadata-json '{\"key\":\"value\"}'","handlingStrategy":"validation","validationCode":"function safeMetadata(value) {\n  // Validate before passing to --metadata-json\n  const obj = typeof value === 'string' ? JSON.parse(value) : value;\n  return JSON.stringify(obj); // guaranteed valid JSON string for the CLI\n}\n// const arg = `--metadata-json ${JSON.stringify(safeMetadata(userObj))}`;","typeGuard":"function isJsonString(value) {\n  try { JSON.parse(value); return true; } catch { return false; }\n}","tryCatchPattern":null,"preventionTips":["Build the metadata string with JSON.stringify on a real object, never by hand.","Pipe-test the JSON (`echo '...' | jq .`) before adding it to the command.","Single-quote the outer JSON in the shell so inner double quotes survive."],"tags":["cli","json","work-items","validation","metadata"],"backgroundTag":null,"analyzedSha":"01e15490f04e29cfefe3896951f43db46994d8ee","analyzedAt":"2026-08-13T00:31:08.655Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}