astral-sh/ruff · error

Expected <Extension>:<LanguageCode> pattern

Error message

Expected <Extension>:<LanguageCode> pattern

What it means

ExtensionPair::from_str parses each --extension value as '<Extension>:<LanguageCode>' by splitting on ':' and requiring exactly two tokens. A value with zero, one, or two-plus colons fails immediately, before the language string is even validated (a bad language yields error #22 instead).

Source

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

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ExtensionPair {
    pub extension: String,
    pub language: Language,
}

impl ExtensionPair {
    const EXPECTED_PATTERN: &'static str = "<Extension>:<LanguageCode> pattern";
}

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

    fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
        let (extension_str, language_str) = {
            let tokens = s.split(':').collect::<Vec<_>>();
            if tokens.len() != 2 {
                bail!("Expected {}", Self::EXPECTED_PATTERN);
            }
            (tokens[0].trim(), tokens[1].trim())
        };
        let extension = extension_str.into();
        let language = Language::from_str(language_str)?;
        Ok(Self {
            extension,
            language,
        })
    }
}

impl From<ExtensionPair> for (String, Language) {
    fn from(value: ExtensionPair) -> Self {
        (value.extension, value.language)
    }
}

View on GitHub (pinned to d1087a4b9e)

Solutions

1. Rewrite as '<Extension>:<LanguageCode>', e.g. --extension 'txt:python'
2. Pass multiple mappings as separate flags or comma-separated values as documented by the flag
3. For permanent mappings, use the project.extension setting in pyproject.toml instead

Example fix

# before
ruff check --extension txt .
# after
ruff check --extension 'txt:python' .

# bash: require exactly one colon in each --extension value
val='txt:python'
if [[ "$(tr -cd ':' <<<"$val" | wc -c)" -ne 1 ]]; then
  echo "need <Extension>:<LanguageCode>, e.g. 'txt:python'" >&2; exit 1
fi
ruff check --extension "$val" .

When it happens

Trigger: Passing --extension txt (missing language), --extension 'txt python' (wrong separator), or a value containing another colon such as an unescaped Windows path --extension 'C:\tmp\x.py:python'.

Common situations: Assuming --extension takes a bare file extension list; using '=' or space instead of ':'; shell quoting that swallows the colon.

Related errors

• Expected <FilePattern>:<RuleCode> pattern
• No files found under the given path
• Unsupported serialization format for statistics: {:?}
• Working directory does not exist
• Expected {}

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