Unity-Technologies/ml-agents · error · RuntimeError

Can't load Demonstration data from an unsupported version ({

Error message

Can't load Demonstration data from an unsupported version ({meta_data_proto.api_version})

What it means

While parsing a .demo file, load_demonstration reads DemonstrationMetaProto records and checks api_version against SUPPORTED_DEMONSTRATION_VERSIONS ({0, 1}). This RuntimeError is raised when the file was written with an API version this ML-Agents release cannot parse, so the binary layout may be incompatible.

Source

Thrown at ml-agents/mlagents/trainers/demo_loader.py:203

    behavior_spec = None
    brain_param_proto = None
    info_action_pairs = []
    total_expected = 0
    for _file_path in file_paths:
        with open(_file_path, "rb") as fp:
            with hierarchical_timer("read_file"):
                data = fp.read()
            next_pos, pos, obs_decoded = 0, 0, 0
            while pos < len(data):
                next_pos, pos = _DecodeVarint32(data, pos)
                if obs_decoded == 0:
                    meta_data_proto = DemonstrationMetaProto()
                    meta_data_proto.ParseFromString(data[pos : pos + next_pos])
                    if (
                        meta_data_proto.api_version
                        not in SUPPORTED_DEMONSTRATION_VERSIONS
                    ):
                        raise RuntimeError(
                            f"Can't load Demonstration data from an unsupported version ({meta_data_proto.api_version})"
                        )
                    total_expected += meta_data_proto.number_steps
                    pos = INITIAL_POS
                if obs_decoded == 1:
                    brain_param_proto = BrainParametersProto()
                    brain_param_proto.ParseFromString(data[pos : pos + next_pos])
                    pos += next_pos
                if obs_decoded > 1:
                    agent_info_action = AgentInfoActionPairProto()
                    agent_info_action.ParseFromString(data[pos : pos + next_pos])
                    if behavior_spec is None:
                        behavior_spec = behavior_spec_from_proto(
                            brain_param_proto, agent_info_action.agent_info
                        )
                    info_action_pairs.append(agent_info_action)
                    if len(info_action_pairs) == total_expected:
                        break

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Re-record the demonstration file using the same ML-Agents release that is doing the training.
2. Upgrade (or downgrade) the ml-agents package so its SUPPORTED_DEMONSTRATION_VERSIONS includes the file's api_version.
3. If the version is merely stale, convert the demo by re-recording in the current Unity project rather than hand-patching the binary.

Example fix

// before
pip install mlagents==0.15.0  # cannot read api_version 2 demos
// after
pip install mlagents==0.28.0  # matches the version that recorded the demo

from mlagents.trainers.demo_loader import load_demonstration, SUPPORTED_DEMONSTRATION_VERSIONS
demo_spec, _, _ = load_demonstration(path)  # call in a preflight check before training

def demo_version_supported(api_version: int) -> bool:
    from mlagents.trainers.demo_loader import SUPPORTED_DEMONSTRATION_VERSIONS
    return api_version in SUPPORTED_DEMONSTRATION_VERSIONS

try:
    demo_spec, pairs, _ = load_demonstration(path)
except RuntimeError as e:
    if "unsupported version" in str(e):
        logger.error("Re-record demos with the current ML-Agents version")
        raise SystemExit(1)
    raise

When it happens

Trigger: load_demonstration called on a .demo file whose DemonstrationMetaProto.api_version is not 0 or 1 — typically a demo recorded by a much newer or older ML-Agents/Unity version.

Common situations: Mixing demo files recorded with a different Unity ML-Agents package version; upgrading the ml-agents repo but keeping old recordings (or vice versa); hand-edited/corrupted meta records producing a bogus version field.

Related errors

• No BrainParameters found in demonstration file at {file_path
• There was a problem reading a message in a SideChannel. Plea
• The actions {} in demonstration do not match the policy's {}
• The demonstrations do not have the same number of observatio
• The shape {demo_obs} for observation {i} in demonstration

AI-assisted analysis of Unity-Technologies/ml-agents@3ecb446f75 (2026-09-02). Data as JSON: /api/errors/2b33b374213ee460. Report an issue: GitHub.