Unrecognized language: `{s}`. Expected one of `python`, `pyi

Error message

Unrecognized language: `{s}`. Expected one of `python`, `pyi`, or `ipynb`.

What it means

`Language::from_str` parses a file-language setting and only accepts `python`, `pyi`, `ipynb` (plus `md` mapped internally). Any other value, including unrecognized spellings or omitted languages, bails with this message telling the user the accepted set.

Source

Thrown at crates/ruff_linter/src/settings/types.rs:445

pub enum Language {
    #[default]
    Python,
    Pyi,
    Ipynb,
    Markdown,
}

impl FromStr for Language {
    type Err = anyhow::Error;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_ascii_lowercase().as_str() {
            "python" => Ok(Self::Python),
            "pyi" => Ok(Self::Pyi),
            "ipynb" => Ok(Self::Ipynb),
            "md" => Ok(Self::Markdown),
            _ => {
                bail!("Unrecognized language: `{s}`. Expected one of `python`, `pyi`, or `ipynb`.")
            }
        }
    }
}

impl From<Language> for SourceType {
    fn from(value: Language) -> Self {
        match value {
            Language::Python => Self::Python(PySourceType::Python),
            Language::Ipynb => Self::Python(PySourceType::Ipynb),
            Language::Pyi => Self::Python(PySourceType::Stub),
            Language::Markdown => Self::Markdown,
        }
    }
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ExtensionPair {

View on GitHub (pinned to 26f38c119c)

Solutions

Use one of the exact accepted strings: `python`, `pyi`, or `ipynb` (or `md` where supported)
Wrap the value only for whitespace issues — parsing lowercases the input, so case is fine but extra words are not
Choose a different extension mapping if you intended a non-Python language; ruff only supports Python-family source kinds

Example fix

# before
".pyx" = "cython"
# after
".pyx" = "python"

Defensive patterns

Strategy: validation

Validate before calling

ALLOWED_LANGUAGES = {"python", "pyi", "ipynb", "md"}
assert language.lower().strip() in ALLOWED_LANGUAGES, f"Unrecognized language: {language}"

Prevention

Use only python, pyi, ipynb (and md where supported) in extension mappings
Copy accepted values from ruff's documented settings, not other tools
Rely on the lowercase-insensitive match: case is fine, but no extra words or whitespace tokens

When it happens

Trigger: Setting an extension-to-language mapping (e.g. `<ext>:<language>` pair) with a language string other than `python`, `pyi`, `ipynb`, or `md` — e.g. `"jsx:javascript"` or capitalized/whitespace variants.

Common situations: Configuring custom file extensions in ruff.toml and typing `Python`, `py`, or `javascript` instead of the exact tokens; copy-pasting from other tools' configs.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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