What causes "{path}: refusing to sort, the sorted output is not valid TOML: {exc}" in Stirling-Tools/Stirling-PDF?

Run the hook against the offending file and read {exc} to see what tomli_w emitted that failed to parse

Stirling-Tools/Stirling-PDF · error · SortError

{path}: refusing to sort, the sorted output is not valid TOM

Error message

{path}: refusing to sort, the sorted output is not valid TOML: {exc}

What it means

After sorting keys via tomli_w.dumps(ordered(original)), the hook re-parses the serialized output as a round-trip safety check (sort_locale_toml.py:55). This SortError means the text tomli_w emitted could not be re-parsed by tomllib -- sorting produced invalid TOML. It is defensive: the script refuses to write a file that would not round-trip. In practice it points at an interaction between the ordered() transform and a TOML feature that tomli_w serializes in a form tomllib rejects, or a tomli_w version change.

Source

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

    return [path for path in result.stdout.split("\0") if path]


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

View on GitHub (pinned to 9ef20dcab8)

Solutions

Run the hook against the offending file and read {exc} to see what tomli_w emitted that failed to parse
Manually sort that file's keys in an editor and exclude it from the auto-sort path, or simplify its TOML to plain tables
Pin or align tomli_w so its output round-trips with the installed tomllib across all environments

Defensive patterns

Strategy: try-catch

Validate before calling

import tomllib, tomli_w
from pathlib import Path

def round_trips(path: str) -> bool:
    text = Path(path).read_text(encoding="utf-8")
    try:
        original = tomllib.loads(text)
        tomllib.loads(tomli_w.dumps(original))  # serialized output re-parses
        return True
    except tomllib.TOMLDecodeError:
        return False

Try / catch

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

Prevention

Keep locale TOML to simple key/value pairs and standard tables
Pin tomli_w and tomllib together so serialization stays stable across environments
If a file triggers this, sort it manually and exclude it rather than forcing the hook

When it happens

Trigger: A locale TOML uses constructs (deeply nested tables, arrays of tables, inline tables, datetimes) that, after the ordered() rebuild on line 22, tomli_w emits in a form tomllib rejects; a tomli_w upgrade changed serialization output for some construct.

Common situations: Upgrading tomli_w in engine dependencies; a locale file using advanced TOML features the simple key-sort was not designed for; cross-environment tomli_w version skew.

Related errors

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