Stirling-Tools/Stirling-PDF · error · SortError

{path}: refusing to sort, sorting would change the file's co

Error message

{path}: refusing to sort, sorting would change the file's contents

What it means

The second round-trip guard at sort_locale_toml.py:58: after re-parsing the sorted output, the resulting table must be deeply equal to the original. Python dict equality ignores insertion order, so this fires only when re-serialization changed the data model itself, not merely key order. The hook refuses to write because sorting would silently alter the file's meaning. It catches sort-induced semantic drift from TOML constructs whose canonical form under tomli_w differs from the parsed structure.

Source

Thrown at scripts/pre-commit/sort_locale_toml.py:59

def sort_file(path: str, fix: bool) -> bool:
    """Rewrite one file if `fix`; return whether it was not already sorted."""
    text = Path(path).read_text(encoding="utf-8")
    try:
        original = tomllib.loads(text)
    except tomllib.TOMLDecodeError as exc:
        raise SortError(f"{path}: invalid TOML: {exc}") from exc

    expected = tomli_w.dumps(ordered(original))
    if expected == text:
        return False

    try:
        reordered = tomllib.loads(expected)
    except tomllib.TOMLDecodeError as exc:
        raise SortError(f"{path}: refusing to sort, the sorted output is not valid TOML: {exc}") from exc
    if reordered != original:
        raise SortError(f"{path}: refusing to sort, sorting would change the file's contents")

    if fix:
        Path(path).write_text(expected, encoding="utf-8")
    return True


def main() -> int:
    args = sys.argv[1:]
    fix = "--fix" in args
    pathspecs = [a for a in args if a != "--fix"]

    offenders: list[str] = []
    errors: list[str] = []
    for path in tracked_files(pathspecs):
        try:
            if sort_file(path, fix):
                offenders.append(path)
        except SortError as exc:

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Manually sort that file's keys in your editor and exclude it from the auto-sort path
2. Reduce the file to plain key/value pairs and standard tables so the round-trip is stable
3. Add a temporary debug print of `original` vs `reordered` to find exactly which key's value model changed, then simplify that construct

import tomllib, tomli_w
from pathlib import Path

def sort_preserves_semantics(path: str) -> bool:
    text = Path(path).read_text(encoding="utf-8")
    try:
        original = tomllib.loads(text)
        reparsed = tomllib.loads(tomli_w.dumps(original))
    except tomllib.TOMLDecodeError:
        return False
    return reparsed == original

try:
    sort_file(path, fix)
except SortError as exc:
    errors.append(str(exc))

When it happens

Trigger: A TOML feature whose canonical form under tomli_w differs from the parsed structure -- array-of-tables, inline tables expanded to standard tables, dotted keys normalized -- so the re-parsed dict no longer equals the original; case-insensitive sort reordering keys whose tomli_w resolution differs.

Common situations: Locale files mixing inline and standard tables for the same data; a tomli_w upgrade changes how it emits a construct; a file with keys differing only by case that the str.lower sort reorders.

Related errors

• {path}: invalid TOML: {exc}
• {path}: refusing to sort, the sorted output is not valid TOM
• Unsupported platform for gitleaks: {platform.system()}/{plat
• No pinned gitleaks checksum for {key}
• gitleaks checksum mismatch: expected {expected}, got {digest

AI-assisted analysis of Stirling-Tools/Stirling-PDF@9ef20dcab8 (2026-08-13). Data as JSON: /api/errors/92ca7f9a49ffd609. Report an issue: GitHub.