astral-sh/ruff · error · clap::Error

ValueValidation

Error message

ValueValidation

What it means

This clap ValueValidation error is constructed manually by ruff's CLI when a `--config` flag value cannot be parsed as valid TOML, or parses as TOML but does not match ruff's configuration schema. Ruff intercepts config parsing failures and re-reports them as a structured clap error so they surface as normal CLI argument errors. The message carries an `InvalidArg` context naming the offending flag.

Solutions

1. Validate the config file by running the same file through `ruff check --config path` or a TOML linter to locate the syntax/schema error
2. Fix the TOML syntax error reported (missing quotes, trailing commas, wrong types)
3. Pin/consult the ruff docs for your installed version to ensure the keys exist and have valid types
4. If embedding config inline, ensure the value is valid TOML for the schema

Example fix

// before (invalid TOML)
# ruff.toml
[lint]
select = E4  // not valid TOML
// after
[lint]
select = ["E4"]

import tomllib
from pathlib import Path
try:
    tomllib.loads(Path("ruff.toml").read_text())
except tomllib.TOMLDecodeError as e:
    raise SystemExit(f"invalid ruff config TOML: {e}")

When it happens

Trigger: Passing `--config` / `--config-file` with a malformed TOML file, or a TOML file whose contents fail ruff's schema validation (e.g. wrong type for a setting, unknown key with strict parsing).

Common situations: Typos in config keys, editing pyproject.toml/ruff.toml by hand and introducing invalid TOML, copying config between projects where a setting's type changed across ruff versions.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Can only write to stdout when formatting from stdin, but…
• Content not correctly formatted
• could not find any tasks matching the given criteria
• could not find `pyproject.toml` in any ancestor of
• could not find task named

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

Appendix: source

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

        let _guard = ValueSourceGuard::new(ValueSource::Cli, false);

        let config_parse_error = match toml::Table::from_str(value) {
            Ok(table) => match Options::from_toml_table(table) {
                Ok(option) => {
                    if option.extend.is_none() {
                        return Ok(SingleConfigArgument::SettingsOverride(Arc::new(option)));
                    }
                    InvalidConfigFlagReason::ExtendPassedViaConfigFlag
                }
                Err(underlying_error) => {
                    InvalidConfigFlagReason::ValidTomlButInvalidRuffSchema(underlying_error)
                }
            },
            Err(underlying_error) => InvalidConfigFlagReason::InvalidToml(underlying_error),
        };

        let mut new_error = clap::Error::new(clap::error::ErrorKind::ValueValidation).with_cmd(cmd);
        if let Some(arg) = arg {
            new_error.insert(
                clap::error::ContextKind::InvalidArg,
                clap::error::ContextValue::String(arg.to_string()),
            );
        }
        new_error.insert(
            clap::error::ContextKind::InvalidValue,
            clap::error::ContextValue::String(value.to_string()),
        );

        let underlying_error = match &config_parse_error {
            InvalidConfigFlagReason::ExtendPassedViaConfigFlag => {
                let tip = config_parse_error.description().into();
                new_error.insert(
                    clap::error::ContextKind::Suggested,
                    clap::error::ContextValue::StyledStrs(vec![tip]),
                );

View on GitHub (pinned to 15f3fe6b15)