kovidgoyal/kitty · error · ValueError

Invalid number with unit: {x}

Error message

Invalid number with unit: {x}

What it means

number_with_unit raises ValueError('Invalid number with unit: {x}') when the whole string does not match the number+unit pattern at all — the value isn't recognizable as a number with an optional unit.

Source

Thrown at kitty/conf/utils.py:83

def unit_float(x: ConvertibleToNumbers) -> float:
    return max(0, min(float(x), 1))


def signed_unit_float(x: ConvertibleToNumbers) -> float:
    return max(-1, min(float(x), 1))


def number_with_unit(x: str, default_unit: str, *extra_units: str) -> tuple[float, str]:
    if (mat := number_unit_pat.match(x)) is not None:
        try:
            value = float(mat.group(1))
        except Exception as e:
            raise ValueError(f'Not a number: {x} with error: {e}')
        unit = mat.group(2) or default_unit
        if unit != default_unit and unit not in extra_units:
            raise ValueError(f'Not a valid unit: {x}. Allowed units are: {default_unit}, {", ".join(extra_units)}')
        return value, unit
    raise ValueError(f'Invalid number with unit: {x}')


def to_bool(x: str) -> bool:
    return x.lower() in ('y', 'yes', 'true')


class ToCmdline:
    def __init__(self) -> None:
        self.override_env: dict[str, str] | None = None

    def __enter__(self) -> 'ToCmdline':
        return self

    def __exit__(self, *a: Any) -> None:
        self.override_env = None

    def filter_env_vars(self, *a: str, **override: str) -> 'ToCmdline':
        remove = frozenset(a)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Supply a plain number or number+allowed unit
2. Quote the config line if generated from shell variables
3. Validate the value before writing the config

Example fix

# before
text_fg_override_threshold
# after
text_fg_override_threshold 20

import re
is_number_with_unit = re.fullmatch(r'[+-]?(\d+\.?\d*|\.\d+)\w*', x) is not None

try:
    v, u = number_with_unit(x, 'px')
except ValueError:
    v, u = 0.0, 'px'

When it happens

Trigger: Config values like 'big', '10 20', '-', or empty strings passed to an option parsed by number_with_unit.

Common situations: Typos, missing values, or shell expansion gone wrong in kitty.conf or programmatically generated config.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Not a number: {x} with error: {e}
• Not a valid unit: {x}. Allowed units are: {default_unit}, {"
• Unknown key action: {action}
• This should be run as kitten broadcast
• No option named: {k}

AI-assisted analysis of kovidgoyal/kitty@6d5d0c4406 (2026-08-27). Data as JSON: /api/errors/d834c74103364af4. Report an issue: GitHub.