affaan-m/ECC · error · Error

Invalid format: . Use text, json, or markdown.

Error message

Invalid format: ${parsed.format}. Use text, json, or markdown.

What it means

After parsing, parseArgs validates parsed.format against the allowlist ['text','json','markdown'] and throws `Invalid format: <value>. Use text, json, or markdown.` for anything else. The format flag controls report output style and is constrained to these three values.

Solutions

Use one of the exact values: text, json, or markdown (lowercase).
Replace abbreviations like md with markdown.
Check the shell/config for an empty or whitespace --format= value and remove it.
Normalize case before invoking if the value comes from an env var: `--format=$(echo "$FMT" | tr 'A-Z' 'a-z')`.

Example fix

// before
node scripts/harness-adapter-compliance.js --format=md

// after
node scripts/harness-adapter-compliance.js --format=markdown

Defensive patterns

Strategy: validation

Validate before calling

const FORMATS = ['text', 'json', 'markdown'];
if (!FORMATS.includes(parsed.format)) {
  throw new Error(`Invalid format: ${parsed.format}. Use text, json, or markdown.`);
}

Type guard

const isFormat = (f) => f === 'text' || f === 'json' || f === 'markdown';

Try / catch

try {
  const parsed = parseArgs(process.argv);
} catch (e) {
  if (e.message.startsWith('Invalid format:')) {
    console.error(e.message);
    process.exit(2);
  }
  throw e;
}

Prevention

Use the exact lowercase values: text, json, markdown — no abbreviations like md.
Lowercase env-sourced values before passing them: ${FMT,,} in bash.
Guard against empty --format= values in generated command lines.
Define the format constant once and reuse it in wrappers.

When it happens

Trigger: Passing --format=yaml, --format=TEXT (uppercase), or an empty --format=; programmatically setting parsed.format to a value from another tool's vocabulary.

Common situations: Copy-pasting flags from a different script that supports more formats; case-sensitivity surprises (XML/TEXT); shell defaults emitting an empty string; typos like 'md' instead of 'markdown'.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at scripts/harness-adapter-compliance.js:60

      continue;
    }

    if (arg === '--root') {
      parsed.root = path.resolve(args[index + 1] || process.cwd());
      index += 1;
      continue;
    }

    if (arg.startsWith('--root=')) {
      parsed.root = path.resolve(arg.slice('--root='.length));
      continue;
    }

    throw new Error(`Unknown argument: ${arg}`);
  }

  if (!['text', 'json', 'markdown'].includes(parsed.format)) {
    throw new Error(`Invalid format: ${parsed.format}. Use text, json, or markdown.`);
  }

  parsed.root = path.resolve(parsed.root);
  return parsed;
}

function printHelp() {
  console.log([
    'Usage: node scripts/harness-adapter-compliance.js [options]',
    '',
    'Validate or render the ECC harness adapter compliance scorecard.',
    '',
    'Options:',
    '  --check                 Fail if adapter records or docs are out of sync',
    '  --format <text|json|markdown>',
    '  --root <path>           Repository root, defaults to cwd',
    '  -h, --help              Show this help',
  ].join('\n'));

View on GitHub (pinned to 8321021c54)