kovidgoyal/kitty · error · ValueError

Invalid underline_exclusion with unrecognized unit: {x}

Error message

Invalid underline_exclusion with unrecognized unit: {x}

What it means

kitty's underline_exclusion option parser accepts a plain number or a number with a 'px' or 'pt' unit suffix. This error fires when the value is not a plain float and its last two characters are not a recognized unit.

Source

Thrown at kitty/options/utils.py:1190

        log_error(f'Invalid shell integration options: {q - allowed_shell_integration_values}, ignoring')
        return q & allowed_shell_integration_values or frozenset({'invalid'})
    return q


def confirm_close(x: str) -> tuple[int, bool]:
    parts = x.split(maxsplit=1)
    num = int(parts[0])
    allow_background = len(parts) > 1 and parts[1] == 'count-background'
    return num, allow_background


def underline_exclusion(x: str) -> tuple[float, Literal['', 'px', 'pt']]:
    try:
        return float(x), ''
    except Exception:
        unit: Literal['pt', 'px'] = x[-2:]  # type: ignore
        if unit not in ('px', 'pt'):
            raise ValueError(f'Invalid underline_exclusion with unrecognized unit: {x}')
        try:
            val = float(x[:-2])
        except Exception:
            raise ValueError(f'Invalid underline_exclusion with non numeric value: {x}')
        return val, unit


def paste_actions(x: str) -> frozenset[str]:
    s = frozenset({'quote-urls-at-prompt', 'confirm', 'filter', 'confirm-if-large', 'replace-dangerous-control-codes', 'replace-newline', 'no-op'})
    q = frozenset(x.lower().split(','))
    if not q.issubset(s):
        raise ValueError(f'Invalid paste actions: {q - s}, ignoring')
    return q


def action_alias(val: str) -> Iterable[tuple[str, str]]:
    parts = val.split(maxsplit=1)
    if len(parts) > 1:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use a plain number (e.g. 3) or a number with px or pt suffix (e.g. 3px, 2pt)
2. Remove unsupported unit suffixes from the value

Example fix

# before
underline_exclusion 3em
# after
underline_exclusion 3px

import re
def valid_underline_exclusion(v: str) -> bool:
    return bool(re.fullmatch(r'-?\d+(\.\d+)?(px|pt)?', v))

When it happens

Trigger: Setting underline_exclusion to something like '3em', '3mm', or a bare non-numeric string; the code tries float(x) first, then checks x[-2:] against ('px','pt') and rejects anything else.

Common situations: Using CSS-style units kitty does not support (em, rem, cm), misspelling px/pt, or passing an empty string.

Related errors

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

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