{"record":{"id":"dc36b6f873b92da6","repo":"Unity-Technologies/ml-agents","slug":"api-versions-of-demonstration-are-incompatible","errorCode":null,"errorMessage":"API versions of demonstration are incompatible.","messagePattern":"API versions of demonstration are incompatible\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"com.unity.ml-agents/Runtime/Communicator/GrpcExtensions.cs","lineNumber":298,"sourceCode":"            };\n            return demoProto;\n        }\n\n        /// <summary>\n        /// Initialize metadata values based on proto object.\n        /// </summary>\n        public static DemonstrationMetaData ToDemonstrationMetaData(this DemonstrationMetaProto demoProto)\n        {\n            var dm = new DemonstrationMetaData\n            {\n                numberEpisodes = demoProto.NumberEpisodes,\n                numberSteps = demoProto.NumberSteps,\n                meanReward = demoProto.MeanReward,\n                demonstrationName = demoProto.DemonstrationName\n            };\n            if (demoProto.ApiVersion != DemonstrationMetaData.ApiVersion)\n            {\n                throw new Exception(\"API versions of demonstration are incompatible.\");\n            }\n            return dm;\n        }\n\n        #endregion\n\n        public static UnityRLInitParameters ToUnityRLInitParameters(this UnityRLInitializationInputProto inputProto)\n        {\n            return new UnityRLInitParameters\n            {\n                seed = inputProto.Seed,\n                numAreas = inputProto.NumAreas,\n                pythonLibraryVersion = inputProto.PackageVersion,\n                pythonCommunicationVersion = inputProto.CommunicationVersion,\n                TrainerCapabilities = inputProto.Capabilities.ToRLCapabilities()\n            };\n        }\n","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/com.unity.ml-agents/Runtime/Communicator/GrpcExtensions.cs#L280-L316","documentation":"GrpcExtensions.ToDemonstrationMetaData throws a plain Exception when demoProto.ApiVersion differs from DemonstrationMetaData.ApiVersion. Demonstration files carry an API version marker; the loader refuses demos written by an incompatible ML-Agents version rather than misparsing them.","triggerScenarios":"Loading a .demo file whose serialized DemoProto.ApiVersion doesn't match the current DemonstrationMetaData.ApiVersion — e.g. a demo recorded with an older/newer ML-Agents release being opened or used for behavioral cloning.","commonSituations":"Replaying old demonstration recordings after upgrading the ML-Agents package; sharing demo files between projects with different ml-agents versions.","solutions":["Regenerate the demonstration with the currently installed ML-Agents version","Downgrade/align the ML-Agents package to the version that recorded the demo","Check the demo file's ApiVersion field against DemonstrationMetaData.ApiVersion before use"],"exampleFix":"// before\n// old ml-agents 0.x demo loaded by ml-agents 1.x\n// after\n// re-record the .demo file with the installed ml-agents version","handlingStrategy":"validation","validationCode":"var apiVersion = DemonstrationMetaData.ApiVersion; // compare against demo's stored ApiVersion before loading\nif (demo.ApiVersion != apiVersion) {\n    Debug.LogError($\"Demo API version {demo.ApiVersion} != required {apiVersion}\");\n}","typeGuard":null,"tryCatchPattern":"try { var meta = demoProto.ToDemonstrationMetaData(); } catch (Exception e) { Debug.LogError(e.Message); }","preventionTips":["Re-record demos after upgrading ML-Agents","Keep demo-producing and demo-consuming package versions aligned","Check the demo header's ApiVersion before loading"],"tags":["unity","ml-agents","demonstration","version-mismatch"],"backgroundTag":"api-version-mismatch","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}