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

Error message

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

What it means

After parsing, platform-audit validates that the requested output format is one of the three supported values: text, json, or markdown. Anything else throws `Invalid format: <value>. Use text, json, or markdown.` A second related check fires when --write is combined with the text format, since machine-readable output is required for file writes.

Solutions

Use exactly one of: --format text, --format json, or --format markdown (lowercase, full words).
Prefer the shorthand flags --json or --markdown instead of --format.
When using --write, always pair it with --json or --markdown (or --format json|markdown).
If the value comes from a variable, normalize it: `fmt=$(echo "$FMT" | tr '[:upper:]' '[:lower:]'); [[ $fmt == md ]] && fmt=markdown`.

Example fix

# before
node scripts/platform-audit.js --format md --write audit.md

# after
node scripts/platform-audit.js --format markdown --write audit.md

Defensive patterns

Strategy: validation

Validate before calling

const FORMATS = ['text', 'json', 'markdown'];
if (!FORMATS.includes(format)) throw new Error(`format must be one of ${FORMATS.join('|')}`);
if (writePath && format === 'text') throw new Error('--write requires json or markdown');

Type guard

const isOutputFormat = (v) => v === 'text' || v === 'json' || v === 'markdown';

Try / catch

try {
  const parsed = parseArgs(process.argv);
} catch (err) {
  if (/^Invalid format/.test(err.message)) {
    console.error(`${err.message} (shorthands: --json, --markdown)`);
    process.exit(2);
  }
  throw err;
}

Prevention

Use full lowercase format names: text, json, markdown — no 'md' or uppercase.
Prefer the --json / --markdown shorthand flags to avoid --format strings entirely.
Always pair --write with a machine-readable format.
Normalize user/config-supplied format values (lowercase, expand aliases) before passing to the CLI.

When it happens

Trigger: Passing --format xml, --format md (abbreviation not accepted), an uppercase value like --format JSON, or --write without switching the format away from the text default.

Common situations: Assuming common abbreviations ('md') or case-insensitivity work; pipelines that emit FORMAT=xml from a template; using --write but forgetting --json/--markdown so the text-default pairing is rejected.

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/3f9c4e405b3d5899. Report an issue: GitHub.

Appendix: source

Thrown at scripts/platform-audit.js:206

      parsed.thresholds.maxDirtyFiles = parseIntegerFlag(arg.slice('--max-dirty-files='.length), '--max-dirty-files');
      continue;
    }

    if (arg === '--use-env-github-token') {
      parsed.useEnvGithubToken = true;
      continue;
    }

    if (arg === '--exit-code') {
      parsed.exitCode = true;
      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.`);
  }

  if (parsed.writePath && parsed.format === 'text') {
    throw new Error('--write requires --json, --markdown, or --format json|markdown');
  }

  parsed.allowUntracked = parsed.allowUntracked.map(normalizeRelativePrefix);

  return parsed;
}

function normalizeRelativePrefix(value) {
  return String(value || '')
    .replace(/\\/g, '/')
    .replace(/^\.\/+/, '')
    .replace(/\/+$/, '') + (String(value || '').endsWith('/') ? '/' : '');
}

View on GitHub (pinned to 8321021c54)