{"record":{"id":"2b33b374213ee460","repo":"Unity-Technologies/ml-agents","slug":"can-t-load-demonstration-data-from-an-unsupported","errorCode":null,"errorMessage":"Can't load Demonstration data from an unsupported version ({meta_data_proto.api_version})","messagePattern":"Can't load Demonstration data from an unsupported version \\((.+?)\\)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"ml-agents/mlagents/trainers/demo_loader.py","lineNumber":203,"sourceCode":"    behavior_spec = None\n    brain_param_proto = None\n    info_action_pairs = []\n    total_expected = 0\n    for _file_path in file_paths:\n        with open(_file_path, \"rb\") as fp:\n            with hierarchical_timer(\"read_file\"):\n                data = fp.read()\n            next_pos, pos, obs_decoded = 0, 0, 0\n            while pos < len(data):\n                next_pos, pos = _DecodeVarint32(data, pos)\n                if obs_decoded == 0:\n                    meta_data_proto = DemonstrationMetaProto()\n                    meta_data_proto.ParseFromString(data[pos : pos + next_pos])\n                    if (\n                        meta_data_proto.api_version\n                        not in SUPPORTED_DEMONSTRATION_VERSIONS\n                    ):\n                        raise RuntimeError(\n                            f\"Can't load Demonstration data from an unsupported version ({meta_data_proto.api_version})\"\n                        )\n                    total_expected += meta_data_proto.number_steps\n                    pos = INITIAL_POS\n                if obs_decoded == 1:\n                    brain_param_proto = BrainParametersProto()\n                    brain_param_proto.ParseFromString(data[pos : pos + next_pos])\n                    pos += next_pos\n                if obs_decoded > 1:\n                    agent_info_action = AgentInfoActionPairProto()\n                    agent_info_action.ParseFromString(data[pos : pos + next_pos])\n                    if behavior_spec is None:\n                        behavior_spec = behavior_spec_from_proto(\n                            brain_param_proto, agent_info_action.agent_info\n                        )\n                    info_action_pairs.append(agent_info_action)\n                    if len(info_action_pairs) == total_expected:\n                        break","sourceCodeStart":185,"sourceCodeEnd":221,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents/mlagents/trainers/demo_loader.py#L185-L221","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-record the demonstration file using the same ML-Agents release that is doing the training.","Upgrade (or downgrade) the ml-agents package so its SUPPORTED_DEMONSTRATION_VERSIONS includes the file's api_version.","If the version is merely stale, convert the demo by re-recording in the current Unity project rather than hand-patching the binary."],"exampleFix":"// before\npip install mlagents==0.15.0  # cannot read api_version 2 demos\n// after\npip install mlagents==0.28.0  # matches the version that recorded the demo","handlingStrategy":"try-catch","validationCode":"from mlagents.trainers.demo_loader import load_demonstration, SUPPORTED_DEMONSTRATION_VERSIONS\ndemo_spec, _, _ = load_demonstration(path)  # call in a preflight check before training","typeGuard":"def demo_version_supported(api_version: int) -> bool:\n    from mlagents.trainers.demo_loader import SUPPORTED_DEMONSTRATION_VERSIONS\n    return api_version in SUPPORTED_DEMONSTRATION_VERSIONS","tryCatchPattern":"try:\n    demo_spec, pairs, _ = load_demonstration(path)\nexcept RuntimeError as e:\n    if \"unsupported version\" in str(e):\n        logger.error(\"Re-record demos with the current ML-Agents version\")\n        raise SystemExit(1)\n    raise","preventionTips":["Record and train with the same ML-Agents/Unity package version","Re-record demos after upgrading ml-agents if versions become incompatible","Preflight-load every demo file before starting long training runs"],"tags":["ml-agents","demonstrations","version-incompatibility","serialization"],"backgroundTag":"unsupported-file-version","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}