ruvnet/ruflo · warning · Error

Config file already exists: ${targetPath}. Use --force to ov

Error message

Config file already exists: ${targetPath}. Use --force to overwrite.

What it means

ConfigFileManager.create refuses to overwrite an existing claude-flow.config.json (resolved from cwd) unless force=true. This is a deliberate guard preventing a re-init from clobbering hand-tuned configuration.

Source

Thrown at v3/@claude-flow/cli/src/services/config-file-manager.ts:125

    const config = this.getConfig(cwd);
    return getNestedValue(config, key);
  }

  /** Set a nested config value by dot-separated key */
  set(cwd: string, key: string, value: unknown): void {
    const config = this.getConfig(cwd);
    setNestedValue(config, key, value);
    this.config = config;
    const targetPath = this.configPath ?? path.resolve(cwd, CONFIG_FILENAMES[0]);
    this.writeAtomic(targetPath, config);
    this.configPath = targetPath;
  }

  /** Create a new config file with defaults */
  create(cwd: string, overrides?: Record<string, unknown>, force?: boolean): string {
    const targetPath = path.resolve(cwd, CONFIG_FILENAMES[0]);
    if (fs.existsSync(targetPath) && !force) {
      throw new Error(`Config file already exists: ${targetPath}. Use --force to overwrite.`);
    }
    const config = { ...DEFAULT_CONFIG, ...overrides };
    this.writeAtomic(targetPath, config);
    this.config = config;
    this.configPath = targetPath;
    return targetPath;
  }

  /** Reset config to defaults */
  reset(cwd: string): string {
    const targetPath = this.configPath ?? path.resolve(cwd, CONFIG_FILENAMES[0]);
    this.writeAtomic(targetPath, DEFAULT_CONFIG);
    this.config = { ...DEFAULT_CONFIG };
    this.configPath = targetPath;
    return targetPath;
  }

  /** Export config to a specific path */

View on GitHub (pinned to 6b01dc5a68)

Solutions

Pass force=true if you intentionally want to overwrite: manager.create(cwd, overrides, true).
Use manager.set(cwd, key, value) to mutate an existing config instead of recreating it.
Call manager.findConfig(cwd) first and skip create() if it returns a path.
Delete the existing file if it is stale.

Example fix

// before
manager.create(cwd, overrides); // throws if config exists

// after
if (!manager.findConfig(cwd)) {
  manager.create(cwd, overrides);
} else {
  manager.set(cwd, 'agents.maxConcurrent', 16);
}

Defensive patterns

Strategy: validation

Validate before calling

const existing = manager.findConfig(cwd);
if (existing) {
  // mutate instead of recreate, or pass force:true intentionally
  manager.set(cwd, key, value);
} else {
  manager.create(cwd, overrides);
}

Try / catch

try {
  manager.create(cwd, overrides);
} catch (e) {
  if ((e as Error).message.startsWith('Config file already exists')) {
    manager.create(cwd, overrides, /* force */ true);
  } else throw e;
}

Prevention

Call findConfig(cwd) before create() to detect an existing config.
Prefer set() to mutate an existing config rather than recreating it.
Only pass force:true when you intend to discard the current config.
Treat config files as user-owned state; do not re-init in automated flows without a check.

When it happens

Trigger: Calling manager.create(cwd) when claude-flow.config.json (or .claude-flow/config.json via CONFIG_FILENAMES[0]) already exists at that path, and force was not passed.

Common situations: Running `init` twice in the same project; a CI step re-initializes over a checked-in config; the file was created by an earlier session and the operator forgot it persists.

Related errors

AI-assisted analysis of ruvnet/ruflo@6b01dc5a68 (2026-08-12). Data as JSON: /api/errors/2695e803bdeafd62. Report an issue: GitHub.