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

InvalidUtf8

InvalidUtf8

Error message

invalid UTF-8 was detected in one or more arguments

What it means

The `ruff option` command (an opaque command used to drive shell completions for option names) parses its OPTION argument with OptionStringParser, which requires the raw OsStr to be valid UTF-8 before matching it against ruff's options metadata. Non-UTF-8 bytes fail immediately with ErrorKind::InvalidUtf8.

Source

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

    type Parser = OptionStringParser;

    fn value_parser() -> Self::Parser {
        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> + '_>> {

View on GitHub (pinned to d1087a4b9e)

Solutions

1. Re-run in a UTF-8 locale (`export LANG=C.UTF-8`).
2. Fix the script that produces the option name so it emits UTF-8.
3. Invoke the command as the generated completion scripts do — with typed text from the shell.

#!/bin/sh
opt="$1"
printf '%s' "$opt" | iconv -f UTF-8 -t UTF-8 >/dev/null 2>&1 || { echo "option name is not UTF-8" >&2; exit 1; }
exec ruff option "$opt"

When it happens

Trigger: Passing a non-UTF-8 byte sequence as the OPTION argument of `ruff option`, e.g. a garbled key produced by a terminal in a legacy locale or a completion script consuming corrupted input.

Common situations: Practically never hit interactively; occurs in scripts with locale problems or corrupted input feeding the completion machinery.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• InvalidUtf8
• InvalidUtf8
• ValueValidation
• The argument `--config={}` cannot be used with `--isolated`
• You cannot specify more than one configuration file on the c

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