yamadashy/repomix · error · RepomixError

--watch cannot be used with split output. Watch mode does no

Error message

--watch cannot be used with split output. Watch mode does not yet support split output files.

What it means

Watch mode packs on every file change; split output would emit numbered part files that the watcher would then pick up as inputs, creating a loop. Repomix therefore rejects `--watch` combined with split output (`output.splitOutput` set via flag or config file) at the start of `runWatchAction`.

Source

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

  if (deps?.signal?.aborted) {
    return;
  }

  // Only load chokidar if no watch function is provided (enables faster tests)
  const resolvedDeps: WatchDeps = deps?.watch ? (deps as WatchDeps) : { ...(await resolveDefaultDeps()), ...deps };

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

View on GitHub (pinned to f465ad9093)

Solutions

Remove the `--split-output` flag when using `--watch`
Delete or unset the split-output setting from repomix.config.json, or use a separate config for watch runs
Run split-output generation as a one-shot command without `--watch`

Example fix

// before
repomix --watch --split-output
// after
repomix --watch   # single output file
# or run separately: repomix --split-output (no --watch)

Defensive patterns

Strategy: validation

Validate before calling

const cfg = JSON.parse(fs.readFileSync('repomix.config.json', 'utf8'));
if (watch && (process.argv.includes('--split-output') || cfg.output?.split != null)) {
  throw new Error('Remove split output before using --watch');
}

Type guard

null

Try / catch

try {
  await runRepomix({ watch: true });
} catch (e) {
  if (e instanceof RepomixError && e.message.includes('--watch cannot be used with split output')) {
    console.error('Disable split output (flag or config) for watch mode.');
  }
  throw e;
}

Prevention

Audit repomix.config.json for split-output settings before enabling --watch
Use separate configs for watch vs one-shot split runs
Remember config-file values are validated only at watch startup, not CLI parse time

When it happens

Trigger: Running `repomix --watch --split-output` (or equivalent), or `repomix --watch` when the config file (repomix.config.json) sets `output.split`/`splitOutput` — the config-based value is only visible on the merged config checked here.

Common situations: A developer with split output enabled in their config file adds `--watch` to iterate on prompts; CLI-only pre-validation in cliRun doesn't see the config value, so the error surfaces at watch startup.

Related errors

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