affaan-m/ECC · error · Error

--write requires --json, --markdown, or --format json|markdo

Error message

--write requires --json, --markdown, or --format json|markdown

What it means

discussion-audit.js supports writing output to a file via --write, but only for structured formats (json or markdown). The default format is 'text', which is designed for terminal display. If --write is provided without explicitly selecting json or markdown format, the post-parse validation at line 148 detects that parsed.writePath is set while parsed.format is still 'text' and throws. This prevents writing unstructured human-readable text to a file.

Source

Thrown at scripts/discussion-audit.js:149

    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');
  }

  return parsed;
}

function buildReport(options) {
  const repos = options.repos.length > 0 ? options.repos : DEFAULT_REPOS;
  const repoReports = repos.map(repo => {
    try {
      return {
        repo,
        discussions: fetchDiscussionSummary(repo, options),
      };
    } catch (error) {
      return {
        repo,
        error: error.message,
        discussions: emptyDiscussionSummary(),

View on GitHub (pinned to 01e15490f0)

Solutions

Add --json or --markdown alongside --write, e.g. --write report.json --json
Use --format json or --format markdown explicitly
If you want text output, redirect stdout to a file instead: node scripts/discussion-audit.js > report.txt

Example fix

// before
node scripts/discussion-audit.js --write report.json
// after
node scripts/discussion-audit.js --write report.json --json
// or
node scripts/discussion-audit.js --write report.json --format json

Defensive patterns

Strategy: validation

Validate before calling

// Ensure --write is always accompanied by a structured format
const argv = process.argv.slice(2);
const hasWrite = argv.includes('--write') || argv.some(a => a.startsWith('--write='));
const hasStructuredFormat = argv.includes('--json') || argv.includes('--markdown')
  || argv.some(a => a.startsWith('--format=json') || a.startsWith('--format=markdown'))
  || (argv.includes('--format') && ['json', 'markdown'].includes((argv[argv.indexOf('--format') + 1] || '').toLowerCase()));
if (hasWrite && !hasStructuredFormat) {
  console.error('--write requires --json, --markdown, or --format json|markdown');
  console.error('Add --json or --markdown to your command.');
  process.exit(1);
}

Try / catch

try {
  const options = parseArgs(process.argv);
} catch (error) {
  if (error.message.includes('--write requires')) {
    console.error(error.message);
    console.error('Add --json or --markdown to the command when using --write.');
    console.error('For text output to a file, redirect stdout: node scripts/discussion-audit.js > report.txt');
    process.exit(2);
  }
  throw error;
}

Prevention

Always pair --write with --json or --markdown — the file extension does not determine the format
For text output, redirect stdout to a file instead of using --write
In CI, use --json --write report.json for machine-readable output

When it happens

Trigger: Passing --write report.json without also passing --json, --markdown, or --format json|markdown. Even though the filename has a .json extension, the script defaults to text format unless told otherwise.

Common situations: Users assuming the file extension determines the format; CI workflows that add --write but forget the format flag; copy-paste from examples that omit the format flag.

Related errors

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