kovidgoyal/kitty · error · ValueError

Not a valid unit: {x}. Allowed units are: {default_unit}, {"

Error message

Not a valid unit: {x}. Allowed units are: {default_unit}, {", ".join(extra_units)}

What it means

number_with_unit raises ValueError when a value carries a unit that is neither the default unit nor one of the allowed extra units. E.g. a pixels-only option given 'em' or 'col'.

Source

Thrown at kitty/conf/utils.py:81

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

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use the default unit (usually no suffix needed)
2. Check the option's allowed units in kitty docs
3. Remove the unit suffix entirely

Example fix

# before
text_fg_override_threshold 20pt
# after
text_fg_override_threshold 20

def valid_unit(x: str, default_unit: str, extra: tuple) -> bool:
    import re
    m = re.match(r'^[+-]?(?:\d+\.?\d*|\.\d+)(.*)$', x)
    u = (m.group(1) if m else '') or default_unit
    return u == default_unit or u in extra

try:
    number_with_unit(x, 'px')
except ValueError:
    x = strip_unit(x)  # fall back to default unit

When it happens

Trigger: Config string like '10em' for an option whose parser was created with default_unit='px' and no 'em' in extra_units.

Common situations: Copying option values between kitty options that accept different unit sets; assuming CSS units are universally allowed.

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}
• Invalid number with unit: {x}
• 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/364317737073cfc7. Report an issue: GitHub.