{"record":{"id":"87a3f863e6eac526","repo":"Stirling-Tools/Stirling-PDF","slug":"path-refusing-to-sort-the-sorted-output-is-not","errorCode":null,"errorMessage":"{path}: refusing to sort, the sorted output is not valid TOML: {exc}","messagePattern":"(.+?): refusing to sort, the sorted output is not valid TOML: (.+?)","errorType":"exception","errorClass":"SortError","httpStatus":null,"severity":"error","filePath":"scripts/pre-commit/sort_locale_toml.py","lineNumber":57,"sourceCode":"    return [path for path in result.stdout.split(\"\\0\") if path]\n\n\ndef sort_file(path: str, fix: bool) -> bool:\n    \"\"\"Rewrite one file if `fix`; return whether it was not already sorted.\"\"\"\n    text = Path(path).read_text(encoding=\"utf-8\")\n    try:\n        original = tomllib.loads(text)\n    except tomllib.TOMLDecodeError as exc:\n        raise SortError(f\"{path}: invalid TOML: {exc}\") from exc\n\n    expected = tomli_w.dumps(ordered(original))\n    if expected == text:\n        return False\n\n    try:\n        reordered = tomllib.loads(expected)\n    except tomllib.TOMLDecodeError as exc:\n        raise SortError(f\"{path}: refusing to sort, the sorted output is not valid TOML: {exc}\") from exc\n    if reordered != original:\n        raise SortError(f\"{path}: refusing to sort, sorting would change the file's contents\")\n\n    if fix:\n        Path(path).write_text(expected, encoding=\"utf-8\")\n    return True\n\n\ndef main() -> int:\n    args = sys.argv[1:]\n    fix = \"--fix\" in args\n    pathspecs = [a for a in args if a != \"--fix\"]\n\n    offenders: list[str] = []\n    errors: list[str] = []\n    for path in tracked_files(pathspecs):\n        try:\n            if sort_file(path, fix):","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/Stirling-Tools/Stirling-PDF/blob/9ef20dcab80b85041912f045e17a6aea1d08f969/scripts/pre-commit/sort_locale_toml.py#L39-L75","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"import tomllib, tomli_w\nfrom pathlib import Path\n\ndef round_trips(path: str) -> bool:\n    text = Path(path).read_text(encoding=\"utf-8\")\n    try:\n        original = tomllib.loads(text)\n        tomllib.loads(tomli_w.dumps(original))  # serialized output re-parses\n        return True\n    except tomllib.TOMLDecodeError:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    sort_file(path, fix)\nexcept SortError as exc:\n    errors.append(str(exc))","preventionTips":["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"],"tags":["toml","pre-commit","round-trip","serialization"],"backgroundTag":null,"analyzedSha":"9ef20dcab80b85041912f045e17a6aea1d08f969","analyzedAt":"2026-08-13T22:11:39.827Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}