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

Error message

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

What it means

Thrown by the argument parser in scripts/harness-adapter-compliance.js when the --format flag receives a value that is not one of the three allowed formats: 'text', 'json', or 'markdown'. The check runs after all args are parsed and validates parsed.format against the whitelist.

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 01e15490f0)

Solutions

Use one of: --format text, --format json, or --format markdown.
Use the convenience flags --text, --json, or --markdown if available.
Check for abbreviations: 'md' is not accepted, use 'markdown'.

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 VALID_FORMATS = ['text', 'json', 'markdown'];
if (!VALID_FORMATS.includes(parsed.format.toLowerCase())) {
  console.error(`Invalid format: ${parsed.format}. Use one of: ${VALID_FORMATS.join(', ')}`);
  process.exit(1);
}

Type guard

function isValidFormat(fmt) {
  return ['text', 'json', 'markdown'].includes(fmt.toLowerCase());
}

Prevention

Use the exact format names: text, json, markdown (not md, txt, or yml).
Validate format input from configuration files before passing to the CLI.
Add autocomplete that only offers valid format values.

When it happens

Trigger: Running `node scripts/harness-adapter-compliance.js --format yaml`, `--format html`, `--format csv`, or any value outside {text, json, markdown}.

Common situations: Using a format from a different tool, a typo, or an abbreviated form like 'md' instead of 'markdown' or 'txt' instead of 'text'.

Related errors

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