kovidgoyal/kitty · warning · ValueError

Warning: unable to parse dircolors line "{line}"

Error message

Warning: unable to parse dircolors line "{line}"

What it means

Raised by load_from_dircolors() in strict mode when a line in a dircolors file does not split into exactly two whitespace-separated tokens (key and value). The dircolors parser only understands simple 'key value' pairs; comments, blank lines and multi-token directives are not supported outside its limited handling. It is a warning-message text wrapped in a ValueError, mirroring what the dircolors(1) utility would print.

Source

Thrown at kittens/tui/dircolors.py:304

                self.codes[code] = color

        return bool(self.codes or self.extensions)

    def load_from_environ(self, envvar: str = 'LS_COLORS') -> bool:
        return self.load_from_lscolors(os.environ.get(envvar) or '')

    def load_from_dircolors(self, database: str, strict: bool = False) -> bool:
        self.clear()

        for line in database.splitlines():
            line = line.split('#')[0].strip()
            if not line:
                continue

            split = line.split()
            if len(split) != 2:
                if strict:
                    raise ValueError(f'Warning: unable to parse dircolors line "{line}"')
                continue

            key, val = split
            if key == 'TERM':
                continue
            if key in CODE_MAP:
                self.codes[CODE_MAP[key]] = val
            elif key.startswith('.'):
                self.extensions[key] = val
            elif strict:
                raise ValueError(f'Warning: unable to parse dircolors line "{line}"')

        return bool(self.codes or self.extensions)

    def load_defaults(self) -> bool:
        self.clear()
        return self.load_from_dircolors(DEFAULT_DIRCOLORS, True)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Fix or remove the offending line in the dircolors file so it is exactly 'KEY value'
2. Generate the file with dircolors -p and edit only supported keys
3. Call load_from_dircolors(data, strict=False) to skip unparseable lines instead of raising

Example fix

# before
result = d.load_from_file('/home/user/.dircolors')  # raises on bad line
# after
result = d.load_from_dircolors(open('/home/user/.dircolors').read(), False)  # skips bad lines

def parseable_dircolors(data: str) -> list[str]:
    bad = []
    for line in data.splitlines():
        if not line or line.startswith('#'):
            continue
        if len(line.split()) != 2:
            bad.append(line)
    return bad

try:
    ok = d.load_from_file(path)
except ValueError as e:
    if 'unable to parse dircolors line' in str(e):
        log.warning('skipping bad dircolors line: %s', e)
    else:
        raise

When it happens

Trigger: Calling load_from_file() or load_defaults() (which calls load_from_dircolors with strict=True) on a dircolors file containing lines with more or fewer than 2 tokens, e.g. 'CONSOLE 01 32' semantics, trailing annotations, or a malformed/custom dircolors file.

Common situations: User has a custom ~/.dircolors/LS_COLORS file from another tool (e.g. vivid, dircolors -p output edited by hand) with unsupported syntax; system-wide /etc/DIR_COLORS containing legacy multi-token lines; stray whitespace or embedded spaces in values.

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

• The font specification %s is invalid as %s does not contain
• This must be run as kitten ask
• This should be run as kitten broadcast
• This must be run as kitten choose-files
• Pipe to kitten was broken while sending data to it

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