You cannot specify more than one configuration file on the…

Error message

You cannot specify more than one configuration file on the command line.

  tip: remove either `--config={first}` or `--config={second}`.
       For more information, try `--help`.

What it means

Ruff's CLI accepts at most one configuration file via `--config`. When a second `--config` argument is supplied, argument parsing bails with this error naming both conflicting paths, since it cannot decide which configuration to use.

Solutions

Remove one of the two `--config` flags, keeping the configuration you intend to apply.
Merge the two TOML files into a single config if both sets of settings are needed.
Fix wrapper scripts so they override, not append, any existing `--config` argument.

Example fix

// before
ruff check --config=a/ruff.toml --config=b/ruff.toml src/
// after
ruff check --config=b/ruff.toml src/

Defensive patterns

Strategy: validation

Validate before calling

# Ensure at most one --config before invoking ruff:
configs = [a for a in sys.argv[1:] if a.startswith('--config=')]
if len(configs) > 1:
    raise SystemExit(f'multiple --config flags: {configs}')

Prevention

Have wrapper scripts override rather than append --config.
Merge multiple TOML configs into one instead of stacking flags.
Check CI matrices for duplicated config arguments from different layers.

When it happens

Trigger: Running ruff with two `--config` flags on one command line, e.g. `ruff check --config=a/ruff.toml --config=b/ruff.toml`, triggering the duplicate-config check in args parsing.

Common situations: Wrapper scripts or CI matrices appending their own `--config` while the base command already has one; copy-pasted commands merging two projects' configs; editor integrations concatenating config arguments.

Related errors

AI-assisted analysis of astral-sh/ruff@15f3fe6b15 (2026-09-05). Data as JSON: /api/errors/0123fc0cccb906d8. Report an issue: GitHub.

Appendix: source

Thrown at crates/ruff/src/args.rs:758

                        &path_dedot::CWD,
                    )?);
                }
                SingleConfigArgument::FilePath(path) => {
                    if isolated {
                        bail!(
                            "\
The argument `--config={}` cannot be used with `--isolated`

  tip: You cannot specify a configuration file and also specify `--isolated`,
       as `--isolated` causes ruff to ignore all configuration files.
       For more information, try `--help`.
",
                            path.display()
                        );
                    }
                    if let Some(ref config_file) = config_file {
                        let (first, second) = (config_file.display(), path.display());
                        bail!(
                            "\
You cannot specify more than one configuration file on the command line.

  tip: remove either `--config={first}` or `--config={second}`.
       For more information, try `--help`.
"
                        );
                    }
                    config_file = Some(path);
                }
            }
        }
        Ok(Self {
            isolated,
            log_level,
            config_file,
            overrides,
            per_flag_overrides,

View on GitHub (pinned to 15f3fe6b15)