astral-sh/ruff · error

Unknown option: {key}

Error message

Unknown option: {key}

What it means

`ruff config <key>` prints the metadata of one configuration option; this error fires when the requested key does not exist in the option registry (Options::metadata()). The key must name a real Ruff configuration option, not a lint rule or a key borrowed from another tool.

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 672bb4edf0)

Solutions

1. Run `ruff config` with no key to list all options, and copy the exact key
2. Fix the typo or section path, e.g. `ruff config line-length`, `ruff config lint.select`
3. Use `ruff config --format json` and search the JSON when scripting

Example fix

# before
ruff config line-lenght

# after
ruff config line-length

# look the key up in the full listing before querying it
ruff config | grep -qw "$1" || { echo "unknown ruff option: $1" >&2; exit 1; }
ruff config "$1"

When it happens

Trigger: Running e.g. `ruff config line-lenght` (typo), `ruff config rules.E501` (a rule, not an option), or `ruff config mypy.strict` (another tool's setting).

Common situations: Typos in option names; wrong section path such as `formatting.line-length` instead of `line-length`; assuming flake8/mypy key names work; scripting `ruff config` with user-supplied keys.

Related errors

• The `--range` option is only supported when formatting a sin
• Provided project path `{project}` is not a directory
• {flag} <reason> cannot contain newline characters
• Unsupported serialization format for statistics: {:?}
• Could not determine source kind for file: {}

AI-assisted analysis of astral-sh/ruff@672bb4edf0 (2026-08-16). Data as JSON: /api/errors/514cd7509bd56c13. Report an issue: GitHub.