yamadashy/repomix · error · RepomixError

--watch cannot be used with stdout output. Watch mode writes

Error message

--watch cannot be used with stdout output. Watch mode writes to a file.

What it means

Watch mode must write its output to a file so it can re-pack and detect changes; stdout mode (`--stdout` or `output.filePath === '-'`) cannot be watched. `runWatchAction` rejects this combination on the merged config.

Source

Thrown at src/cli/actions/watchAction.ts:90

  logger.trace('Watch mode: loaded CLI options:', redactOptionsForLog(cliOptions));

  const config = await buildMergedConfig(cwd, cliOptions);

  // Watch-specific incompatibilities. Each of these is independently incompatible with
  // --watch and can also be set via the config file (which validateWatchOptions in cliRun,
  // CLI-flags-only, does not see), so re-check them on the merged config here. They are
  // checked individually rather than via the shared validateConflictingOptions so the error
  // always names --watch instead of a (potentially confusing) pairwise conflict.
  if (config.output.splitOutput !== undefined) {
    // Split output would create numbered files that the watcher then picks up, looping.
    throw new RepomixError(
      '--watch cannot be used with split output. Watch mode does not yet support split output files.',
    );
  }
  // `output: "-"` resolves to stdout mode via filePath === '-', the same as --stdout.
  if (config.output.stdout || config.output.filePath === '-') {
    throw new RepomixError('--watch cannot be used with stdout output. Watch mode writes to a file.');
  }
  if (config.skillGenerate !== undefined) {
    throw new RepomixError(
      '--watch cannot be used with --skill-generate. Watch mode does not support skill generation.',
    );
  }
  if (config.output.copyToClipboard) {
    throw new RepomixError(
      '--watch cannot be used with --copy. Watch mode re-packs on every change, which would repeatedly overwrite the clipboard.',
    );
  }

  const targetPaths = directories.map((directory) => path.resolve(cwd, directory));

  // Run initial pack
  const packResult = await runPack(targetPaths, config, cliOptions);
  reportResults(cwd, packResult, config, cliOptions);
  logger.log(pc.dim(`\nWatching ${packResult.safeFilePaths.length} files for changes... (Ctrl+C to stop)\n`));

View on GitHub (pinned to f465ad9093)

Solutions

Drop `--stdout` when using `--watch`
Remove `stdout: true` or `filePath: "-"` from the config file for watch runs
Write to a real file with `--watch` and `tail -f`/re-read the file instead of piping stdout

Example fix

// before
repomix --watch --stdout | ai-tool
// after
repomix --watch   # writes repomix-output.xml
ai-tool < repomix-output.xml

Defensive patterns

Strategy: validation

Validate before calling

if (watch && (stdout || filePath === '-')) {
  throw new Error('--watch requires a real output file, not stdout');
}

Type guard

null

Try / catch

try {
  await runRepomix({ watch: true });
} catch (e) {
  if (e instanceof RepomixError && e.message.includes('--watch cannot be used with stdout')) {
    console.error('Drop --stdout (or filePath "-") when watching.');
  }
  throw e;
}

Prevention

Never pair --watch with --stdout; write to a file and tail it instead
Check config for output.stdout: true or filePath: '-' before watch runs

When it happens

Trigger: Running `repomix --watch --stdout`, or `repomix --watch` with `output.stdout: true` or `output.filePath: "-"` set in the config file.

Common situations: A user who normally pipes repomix output to another tool (`repomix --stdout | llm ...`) tries adding `--watch` to refresh the piped output automatically.

Related errors

AI-assisted analysis of yamadashy/repomix@f465ad9093 (2026-08-29). Data as JSON: /api/errors/06a20a2ac047712d. Report an issue: GitHub.