affaan-m/ECC · error · Error

Invalid --metadata-json

Error message

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

What it means

parseMetadataJson parses the --metadata-json option string with JSON.parse. On a SyntaxError it rethrows with the original parser message appended, so the developer can see exactly what the JSON parser objected to. A null/absent value returns null and does not throw.

Solutions

1. Read the appended error.message — it points at the exact JSON syntax problem
2. Validate the JSON in a linter/`node -e 'JSON.parse(...)'` before passing it
3. Use double quotes for keys and string values; no trailing commas
4. Fix shell quoting: wrap the whole JSON in single quotes on POSIX, escape carefully on Windows
5. Prefer passing the JSON via a file or environment variable when quoting gets complex

Example fix

// before
node scripts/work-items.js add --metadata-json "{status: 'draft'}"
// after
node scripts/work-items.js add --metadata-json '{"status":"draft"}'

function isValidJsonString(s) {
  if (typeof s !== 'string' || s.length === 0) return false;
  try { JSON.parse(s); return true; } catch { return false; }
}
// before invoking:
if (!isValidJsonString(metadataJson)) throw new Error('metadata-json is not valid JSON');

function isJsonObject(value) {
  return value !== null && typeof value === 'object' && !Array.isArray(value);
}

try {
  const payload = buildUpsertPayload(options);
} catch (err) {
  if (err.message.startsWith('Invalid --metadata-json:')) {
    console.error('Fix the JSON syntax in --metadata-json (double-quoted keys, no trailing commas).');
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: `--metadata-json "{name: 1}"` (unquoted keys), single quotes instead of double quotes, trailing commas, or a shell-mangled string where quotes were stripped, leaving invalid JSON for JSON.parse.

Common situations: Shell quoting problems — the most common cause: `--metadata-json '{"a":1}'` working on one shell but mangled on Windows cmd or through another layer of interpolation; hand-written JSON with JS-style syntax; empty string passed due to an unset variable.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

• all overlays must be readable local files
• all takes must be readable local files
• application request must be a JSON object
• Arguments must not contain NUL bytes.
• asset name must be a simple filename stem (letters, digits…

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/d380f4adf354852e. Report an issue: GitHub.

Appendix: 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 8321021c54)