github/spec-kit · error · ValidationError

.extensionignore is not valid UTF-8: {ignore_file} ({e.reaso

Error message

.extensionignore is not valid UTF-8: {ignore_file} ({e.reason} at byte {e.start})

What it means

Error ".extensionignore is not valid UTF-8: {ignore_file} ({e.reason} at byte {e.start})" thrown in github/spec-kit.

Source

Thrown at src/specify_cli/extensions/__init__.py:1251

        # Pin UTF-8 explicitly: ``Path.read_text`` defaults to the system
        # locale codec on Windows (cp1252 / gb2312 / cp932), which silently
        # corrupts multibyte patterns when the file is shared across
        # machines with different locales. The next line already
        # normalises backslashes "so Windows-authored files work" — the
        # codebase already expects Windows authors to write this file.
        #
        # A file that is not valid UTF-8 is a user-authoring mistake, so
        # surface it as ``ValidationError`` with a pointer to the offending
        # byte — the same pattern ``ExtensionManifest._load_yaml`` uses
        # for ``extension.yml`` (see ``UnicodeDecodeError`` handler in
        # this module). Without the wrap, the raw ``UnicodeDecodeError``
        # would abort installation with a Python traceback instead of a
        # clear message naming the file.
        try:
            raw = ignore_file.read_text(encoding="utf-8")
        except UnicodeDecodeError as e:
            raise ValidationError(
                f".extensionignore is not valid UTF-8: {ignore_file} "
                f"({e.reason} at byte {e.start})"
            )
        lines: List[str] = raw.splitlines()

        # Normalise backslashes in patterns so Windows-authored files work
        normalised: List[str] = []
        for line in lines:
            stripped = line.strip()
            if stripped and not stripped.startswith("#"):
                normalised.append(stripped.replace("\\", "/"))
            else:
                # Preserve blanks/comments so pathspec line numbers stay stable
                normalised.append(line)

        # Always ignore the .extensionignore file itself
        normalised.append(".extensionignore")

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Re-save .extensionignore as UTF-8 text, or remove the invalid bytes at the reported offset.

When it happens

Trigger: Thrown at src/specify_cli/extensions/__init__.py:1251 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of github/spec-kit@bf88c9f9a8 (2026-08-14). Data as JSON: /api/errors/767c6193d11e646c. Report an issue: GitHub.