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

ValueValidation

ValueValidation

Error message

invalid value '{invalid_value}' for '{invalid_arg}'

What it means

When `--config` receives inline TOML, ruff parses it and validates it against its settings schema. Any failure — malformed TOML, unknown or incorrectly typed options, or smuggling `extend` through the flag — is reported as a clap ValueValidation error whose contexts carry the invalid value and argument name, with the underlying InvalidConfigFlagReason rendered alongside.

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 d1087a4b9e)

Solutions

1. Read the reason printed after the clap message — it distinguishes invalid TOML from a schema rejection and names the failing option.
2. Validate the snippet with a TOML parser first, e.g. `python -c "import tomllib; tomllib.loads(open('/dev/stdin').read())"`.
3. Check the option name and type against `ruff help` and the settings reference for the installed version.
4. Move the settings into pyproject.toml and pass its path via --config to iterate with better error reporting.

Example fix

# before: value has the wrong type for the schema
ruff check --config 'line-length = "100"' .

# after: integer, as the schema requires
ruff check --config 'line-length = 100' .

# validate inline TOML before handing it to ruff
printf '%s' 'line-length = 100' | python -c 'import sys, tomllib; tomllib.loads(sys.stdin.read())' \
  && ruff check --config 'line-length = 100' .

When it happens

Trigger: `ruff check --config 'select=['` (broken TOML), `--config 'line-length = "many"'` (wrong type for the schema), `--config 'extend = "base.toml"'` (extend not allowed via the flag), or an option name that does not exist in the installed ruff version.

Common situations: Shell quoting mistakes; options copied from a newer or older ruff version's docs; YAML/JSON habits (unquoted or differently-cased keys) carried into TOML.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• InvalidUtf8
• The argument `--config={}` cannot be used with `--isolated`
• You cannot specify more than one configuration file on the c
• No files found under the given path
• Unsupported serialization format for statistics: {:?}

AI-assisted analysis of astral-sh/ruff@d1087a4b9e (2026-08-20). Data as JSON: /api/errors/5fc4817019e7cd05. Report an issue: GitHub.