affaan-m/ECC · error · Error

Invalid --metadata-json: ${error.message}

Error message

Invalid --metadata-json: ${error.message}

What it means

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).

Source

Thrown at scripts/work-items.js:129

    } else if (!arg.startsWith('-')) {
      parsed.positionals.push(arg);
    } else {
      throw new Error(`Unknown argument: ${arg}`);
    }
  }

  return parsed;
}

function parseMetadataJson(value) {
  if (value === undefined || value === null) {
    return null;
  }

  try {
    return JSON.parse(value);
  } catch (error) {
    throw new Error(`Invalid --metadata-json: ${error.message}`);
  }
}

function resolveWorkItemId(options) {
  return options.id || options.positionals[0] || null;
}

function normalizeLimit(value) {
  const parsed = Number.parseInt(value, 10);
  if (!Number.isFinite(parsed) || parsed <= 0) {
    throw new Error(`Invalid limit: ${value}`);
  }
  return parsed;
}

function runGhJson(args) {
  const shimPath = process.env.ECC_GH_SHIM;
  const command = shimPath ? process.execPath : 'gh';

View on GitHub (pinned to 01e15490f0)

Solutions

1. Validate the JSON with a linter or `echo '<json>' | jq .` before passing it.
2. Use single quotes around a double-quoted JSON object in the shell: `--metadata-json '{"key":"value"}'`.
3. If building the string programmatically, use JSON.stringify on a real object rather than hand-concatenating.

Example fix

// before
node scripts/work-items.js upsert --title X --metadata-json "{bad}"

// after
node scripts/work-items.js upsert --title X --metadata-json '{"key":"value"}'

function safeMetadata(value) {
  // Validate before passing to --metadata-json
  const obj = typeof value === 'string' ? JSON.parse(value) : value;
  return JSON.stringify(obj); // guaranteed valid JSON string for the CLI
}
// const arg = `--metadata-json ${JSON.stringify(safeMetadata(userObj))}`;

function isJsonString(value) {
  try { JSON.parse(value); return true; } catch { return false; }
}

When it happens

Trigger: `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.

Common situations: 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.

Related errors

• --json may only be provided once
• Missing value for ${arg}
• Unknown argument: ${arg}
• Invalid limit: ${value}
• ${displayCommand} returned invalid JSON: ${error.message}

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/d380f4adf354852e. Report an issue: GitHub.