Unity-Technologies/ml-agents · error · Exception

API versions of demonstration are incompatible.

Error message

API versions of demonstration are incompatible.

What it means

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.

Source

Thrown at com.unity.ml-agents/Runtime/Communicator/GrpcExtensions.cs:298

            };
            return demoProto;
        }

        /// <summary>
        /// Initialize metadata values based on proto object.
        /// </summary>
        public static DemonstrationMetaData ToDemonstrationMetaData(this DemonstrationMetaProto demoProto)
        {
            var dm = new DemonstrationMetaData
            {
                numberEpisodes = demoProto.NumberEpisodes,
                numberSteps = demoProto.NumberSteps,
                meanReward = demoProto.MeanReward,
                demonstrationName = demoProto.DemonstrationName
            };
            if (demoProto.ApiVersion != DemonstrationMetaData.ApiVersion)
            {
                throw new Exception("API versions of demonstration are incompatible.");
            }
            return dm;
        }

        #endregion

        public static UnityRLInitParameters ToUnityRLInitParameters(this UnityRLInitializationInputProto inputProto)
        {
            return new UnityRLInitParameters
            {
                seed = inputProto.Seed,
                numAreas = inputProto.NumAreas,
                pythonLibraryVersion = inputProto.PackageVersion,
                pythonCommunicationVersion = inputProto.CommunicationVersion,
                TrainerCapabilities = inputProto.Capabilities.ToRLCapabilities()
            };
        }

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Regenerate the demonstration with the currently installed ML-Agents version
2. Downgrade/align the ML-Agents package to the version that recorded the demo
3. Check the demo file's ApiVersion field against DemonstrationMetaData.ApiVersion before use

Example fix

// before
// old ml-agents 0.x demo loaded by ml-agents 1.x
// after
// re-record the .demo file with the installed ml-agents version

var apiVersion = DemonstrationMetaData.ApiVersion; // compare against demo's stored ApiVersion before loading
if (demo.ApiVersion != apiVersion) {
    Debug.LogError($"Demo API version {demo.ApiVersion} != required {apiVersion}");
}

try { var meta = demoProto.ToDemonstrationMetaData(); } catch (Exception e) { Debug.LogError(e.Message); }

When it happens

Trigger: 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.

Common situations: Replaying old demonstration recordings after upgrading the ML-Agents package; sharing demo files between projects with different ml-agents versions.

Related errors

• Variable Length Observations are not supported by the traine
• There was a problem reading a message in a SideChannel. Plea
• Demonstration import error.
• Index out of bounds, expected a number between 0 and {Length
• Enumerator not started.

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