pytorch/pytorch · error · RuntimeError

Schema version downgraded from {commit.base['SCHEMA_VERSION'

Error message

Schema version downgraded from {commit.base['SCHEMA_VERSION']} to {commit.result['SCHEMA_VERSION']}.

What it means

Raised by scripts/export/update_schema.py after regenerating the export flatbuffer schema YAML when the newly computed SCHEMA_VERSION is lower than the version recorded in the existing schema.yaml. Version numbers are monotonically increasing; a downgrade means schema.py changes made older serialized artifacts unreadable or the wrong baseline file was compared, so the script refuses to overwrite the YAML.

Source

Thrown at scripts/export/update_schema.py:35

        help="Print the schema instead of writing it to file.",
    )
    parser.add_argument(
        "--force-unsafe",
        action="store_true",
        help="!!! Only use this option when you are a chad. !!! Force to write the schema even if schema validation doesn't pass.",
    )
    args = parser.parse_args()

    assert os.path.exists(args.prefix), (
        f"Assuming path {args.prefix} is the root of pytorch directory, but it doesn't exist."
    )

    commit = schema_check.update_schema()

    abs_yaml_path = os.path.join(args.prefix, commit.yaml_path)
    if os.path.exists(abs_yaml_path):
        if commit.result["SCHEMA_VERSION"] < commit.base["SCHEMA_VERSION"]:
            raise RuntimeError(
                f"Schema version downgraded from {commit.base['SCHEMA_VERSION']} to {commit.result['SCHEMA_VERSION']}."
            )

        if commit.result["TREESPEC_VERSION"] < commit.base["TREESPEC_VERSION"]:
            raise RuntimeError(
                f"Treespec version downgraded from {commit.base['TREESPEC_VERSION']} to {commit.result['TREESPEC_VERSION']}."
            )
    else:
        assert args.force_unsafe, (
            f"Existing schema yaml file not found in {abs_yaml_path}, please check if you provided correct prefix path, or use --force-unsafe to try again."
        )

    next_version, reason = schema_check.check(commit, args.force_unsafe)

    if next_version is not None and next_version != commit.result["SCHEMA_VERSION"]:
        raise RuntimeError(
            f"Schema version is not updated from {commit.base['SCHEMA_VERSION']} to {next_version}.\n"
            + "Please either:\n"

View on GitHub (pinned to dcd2ecae77)

Solutions

  1. Check out the schema.yaml (and schema.py) from the same commit so base and result are consistent, then re-run
  2. If the downgrade is intentional (true revert of a schema change), re-run with --force-unsafe to accept the downgrade
  3. Verify with git log/diff on the schema files which commit bumped the version and align your tree to it

Example fix

# before
git checkout old-schema-pr -- torch/_export/serde/schema.py
python scripts/export/update_schema.py --prefix .
# after
git checkout main -- torch/_export/serde/schema.py torch/_export/serde/schema.yaml
python scripts/export/update_schema.py --prefix .  # or add --force-unsafe for a true revert
Defensive patterns

Strategy: validation

Validate before calling

import yaml

def versions(path: str) -> dict:
    return yaml.safe_load(open(path))

base = versions("torch/_export/serde/schema.yaml")
assert result["SCHEMA_VERSION"] >= base.get("SCHEMA_VERSION", 0), "schema version would downgrade"

Try / catch

try:
    subprocess.run([sys.executable, "scripts/export/update_schema.py", "--prefix", "."], check=True)
except subprocess.CalledProcessError as e:
    if "downgraded" in (e.stdout or ""):
        # realign schema.py/schema.yaml to one commit, or pass --force-unsafe deliberately
        raise
    raise

Prevention

When it happens

Trigger: Running python scripts/export/update_schema.py --prefix <pytorch root> when the checked-out schema.yaml has a higher SCHEMA_VERSION than what the current torch/_export or serialization code produces — e.g. after checking out an older commit of schema.py while keeping a newer generated schema.yaml, or after a partial revert of a version bump.

Common situations: Rebasing or switching branches and having a stale generated schema.yaml. Reverting a PR that bumped SCHEMA_VERSION without regenerating from the reverted state. Mixing files from different commits after a conflict resolution.

Related errors

AI-assisted analysis of pytorch/pytorch@dcd2ecae77 (2026-08-14). Data as JSON: /api/errors/1cd059b6e7069ada. Report an issue: GitHub.