kovidgoyal/kitty · warning · ValueError

Warning: unable to parse dircolors 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.

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
• Aborted by user!
• is unknown for clear_terminal, using reset
• allow_fallback values must be a subset of shifted, ascii…
• Application escape mode is not supported, the extended…

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

Appendix: 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)