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

ValueValidation

ValueValidation

Error message

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

What it means

The OPTION argument of `ruff option` must be a known ruff settings key: `OptionString::from_str` checks `Options::metadata().has(s)`. An unknown name fails the parse and clap reports ValueValidation with the invalid value and argument name inserted as context.

Source

Thrown at crates/ruff/src/commands/completions/config.rs:124

        OptionStringParser
    }
}

impl TypedValueParser for OptionStringParser {
    type Value = OptionString;

    fn parse_ref(
        &self,
        cmd: &clap::Command,
        arg: Option<&clap::Arg>,
        value: &std::ffi::OsStr,
    ) -> Result<Self::Value, clap::Error> {
        let value = value
            .to_str()
            .ok_or_else(|| clap::Error::new(clap::error::ErrorKind::InvalidUtf8))?;

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

    fn possible_values(&self) -> Option<Box<dyn Iterator<Item = PossibleValue> + '_>> {
        let mut visitor = CollectOptionsVisitor::default();
        Options::metadata().record(&mut visitor);

View on GitHub (pinned to d1087a4b9e)

Solutions

1. List valid names via `ruff option --help` (possible values are enumerated) or tab completion.
2. Fix the typo or use the current option name for your ruff version.
3. Regenerate shell completions (`ruff generate-completions <shell>`) after upgrading so cached names are current.

# only pass names ruff actually knows
if ruff option --help | grep -Fxq -- "$opt"; then
  ruff option "$opt"
else
  echo "unknown ruff option: $opt" >&2; exit 1
fi

When it happens

Trigger: `ruff option line-lenght` — a typo'd, renamed, or version-mismatched option name, including dotted sub-table names like `lint.select`.

Common situations: Completion of an option renamed between ruff versions; typos; stale shell completion caches referencing old option names.

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/c5408bc06a485677. Report an issue: GitHub.