What causes "Unknown option: {key}" in astral-sh/ruff?

Run `ruff config` with no key to list all valid option names, then use the exact spelling.

Unknown option

Error message

Unknown option: {key}

What it means

`ruff config <key>` looks up `key` among the options declared in `Options` metadata and errors when the key is not a known Ruff configuration option. It tells the user the requested option name does not exist in Ruff's settings schema.

Solutions

Run `ruff config` with no key to list all valid option names, then use the exact spelling.
Check `ruff check --help` and the settings documentation for renamed keys (e.g. top-level `line-length` vs deprecated nested names).
If the option belongs to a plugin or another tool, remove it from the Ruff config and configure the correct tool instead.

Example fix

// before
$ ruff config max-line-lenght
// after
$ ruff config line-length

Defensive patterns

Strategy: validation

Validate before calling

KEY="line-length"
ruff config 2>/dev/null | grep -qx "$KEY" && ruff config "$KEY" || echo "unknown option: $KEY"

Try / catch

match ruff_config(key) {
    Err(e) if e.to_string().starts_with("Unknown option: ") => {
        eprintln!("Invalid key '{}'; run `ruff config` to list valid options", key);
    }
    other => other?,
}

Prevention

List valid keys with `ruff config` before scripting lookups.
Copy option names from the settings documentation rather than memory.
When upgrading Ruff, diff renamed/removed options from the changelog.

When it happens

Trigger: Running `ruff config <key>` (or `ruff config --help <key>`-style lookup) where `<key>` is not found by `Options::metadata().find(key)`.

Common situations: Typos in the option name, asking about a setting from another tool (e.g. Flake8's `max-line-length` or an old pre-0.2 nested name), or querying settings that were renamed or removed in newer Ruff versions.

Related errors

AI-assisted analysis of astral-sh/ruff@26f38c119c (2026-09-05). Data as JSON: /api/errors/514cd7509bd56c13. Report an issue: GitHub.

Appendix: source

Thrown at crates/ruff/src/commands/config.rs:25

#[expect(clippy::print_stdout)]
pub(crate) fn config(key: Option<&str>, format: HelpFormat) -> Result<()> {
    match key {
        None => {
            let metadata = Options::metadata();
            match format {
                HelpFormat::Text => {
                    println!("{metadata}");
                }

                HelpFormat::Json => {
                    println!("{}", serde_json::to_string_pretty(&metadata)?);
                }
            }
        }
        Some(key) => match Options::metadata().find(key) {
            None => {
                return Err(anyhow!("Unknown option: {key}"));
            }
            Some(entry) => match format {
                HelpFormat::Text => {
                    print!("{entry}");
                }

                HelpFormat::Json => {
                    println!("{}", serde_json::to_string_pretty(&entry)?);
                }
            },
        },
    }
    Ok(())
}

View on GitHub (pinned to 26f38c119c)