affaan-m/ECC · error · Error

--write requires --json or --markdown

Error message

--write requires --json or --markdown

What it means

In scripts/status.js main(), the --write option only works when a machine-readable format (--json or --markdown) was selected, because only those code paths produce a serializable `output` string to save. When a writePath is set but the human (printHuman) path is taken, the script throws "--write requires --json or --markdown" instead of silently ignoring --write.

Solutions

1. Add --json or --markdown alongside --write.
2. Remove --write if you only want the human-readable console output.
3. In wrappers, only pass --write when a format flag is also present.

Example fix

// before
node scripts/status.js --write out.txt
// after
node scripts/status.js --json --write out.json

const wantsWrite = process.argv.includes('--write');
const hasFormat = process.argv.includes('--json') || process.argv.includes('--markdown');
if (wantsWrite && !hasFormat) throw new Error('--write requires --json or --markdown');

try {
  runStatus(argv);
} catch (e) {
  if (e.message.includes('--write requires')) {
    console.error('Add --json or --markdown when using --write.');
    process.exitCode = 1;
  } else throw e;
}

When it happens

Trigger: Running `node scripts/status.js --write out.txt` without --json or --markdown; main() reaches the else branch (human output) and, seeing options.writePath set, throws.

Common situations: Assuming --write works for the default human-readable output; stripping the format flag from a command line while keeping --write; wrapper scripts that add --write unconditionally.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

• --write requires --json, --markdown, or --format…
• Agents directory not found
• --all-harnesses and --harness are mutually exclusive.
• all overlays must be readable local files
• all takes must be readable local files

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

Appendix: source

Thrown at scripts/status.js:528

      installStateProjection,
    };
    payload.githubCoordination = summarizeGithubCoordination(payload.workItems);

    if (options.json) {
      const output = `${JSON.stringify(payload, null, 2)}\n`;
      if (options.writePath) {
        writeOutput(options.writePath, output);
      }
      process.stdout.write(output);
    } else if (options.markdown) {
      const output = renderMarkdown(payload);
      if (options.writePath) {
        writeOutput(options.writePath, output);
      }
      process.stdout.write(output);
    } else {
      if (options.writePath) {
        throw new Error('--write requires --json or --markdown');
      }
      printHuman(payload);
    }

    if (options.exitCode && payload.readiness.status !== 'ok') {
      process.exitCode = 2;
    }
  } catch (error) {
    console.error(`Error: ${error.message}`);
    process.exit(1);
  } finally {
    if (store) {
      store.close();
    }
  }
}

if (require.main === module) {

View on GitHub (pinned to 8321021c54)