What causes "Variable Length Observations are not supported by the trainer" in Unity-Technologies/ml-agents?

Use a trainer/Python ml-agents version that supports VariableLengthObservation (upgrade the Python package and match Unity package versions)

Unity-Technologies/ml-agents · error · UnityAgentsException

Variable Length Observations are not supported by the traine

Error message

Variable Length Observations are not supported by the trainer

What it means

ML-Agents throws this when an observation's dimension properties indicate variable-size (DimensionProperty.VariableSize) but the connected trainer does not declare VariableLengthObservation support in its capabilities. The trainer and Unity side disagree on supported observation formats, so communication is refused before training starts.

Source

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

                {
                    observationProto.CompressedChannelMapping.AddRange(compressionSpec.CompressedChannelMapping);
                }
            }

            // Add the dimension properties to the observationProto
            var dimensionProperties = obsSpec.DimensionProperties;
            for (int i = 0; i < dimensionProperties.Length; i++)
            {
                observationProto.DimensionProperties.Add((int)dimensionProperties[i]);
            }

            // Checking trainer compatibility with variable length observations
            if (dimensionProperties == new InplaceArray<DimensionProperty>(DimensionProperty.VariableSize, DimensionProperty.None))
            {
                var trainerCanHandleVarLenObs = Academy.Instance.TrainerCapabilities == null || Academy.Instance.TrainerCapabilities.VariableLengthObservation;
                if (!trainerCanHandleVarLenObs)
                {
                    throw new UnityAgentsException("Variable Length Observations are not supported by the trainer");
                }
            }

            for (var i = 0; i < shape.Length; i++)
            {
                observationProto.Shape.Add(shape[i]);
            }

            var sensorName = sensor.GetName();
            if (!string.IsNullOrEmpty(sensorName))
            {
                observationProto.Name = sensorName;
            }

            observationProto.ObservationType = (ObservationTypeProto)obsSpec.ObservationType;
            return observationProto;
        }

View on GitHub (pinned to 3ecb446f75)

Solutions

Use a trainer/Python ml-agents version that supports VariableLengthObservation (upgrade the Python package and match Unity package versions)
Make the sensor emit fixed-size observations (pad/crop to a constant shape) and return fixed DimensionProperty.None properties
Remove the VariableSize dimension property from the sensor's ObservationSpec

Example fix

// before
var spec = ObservationSpec.Vector(DimProperty.VariableSize, DimProperty.None);
// after
var spec = ObservationSpec.Vector(FIXED_SIZE); // pad variable data to fixed size

Defensive patterns

Strategy: validation

Validate before calling

var caps = Academy.Instance.TrainerCapabilities;
bool varLenOk = caps == null || caps.VariableLengthObservation;
bool needsVarLen = sensor.GetObservationSpec().DimensionProperties.Contains(DimensionProperty.VariableSize);
if (needsVarLen && !varLenOk) throw new InvalidOperationException("Trainer cannot handle variable-length observations; pad to fixed size.");

Try / catch

try { /* connect trainer / build observation proto */ }
catch (UnityAgentsException e) when (e.Message == "Variable Length Observations are not supported by the trainer")
{ Debug.LogError("Upgrade the ml-agents Python package or make the sensor fixed-size."); }

Prevention

Keep com.unity.ml-agents and the Python ml-agents package versions in sync
Pad variable-size sensor data to a fixed shape and declare fixed DimensionProperty.None
Check TrainerCapabilities.VariableLengthObservation before enabling variable-size sensors

When it happens

Trigger: A sensor reports VariableSize dimension properties (e.g. via GetObservationSpec with variable dimension properties) while the connected trainer/Python package has capabilities.VariableLengthObservation == false; TrainerCapabilities is non-null and lacks the flag.

Common situations: Version mismatch between the ml-agents Python package and the Unity com.unity.ml-agents package; custom sensors with dynamic shapes (e.g. ragged lists of entities) trained with older trainers that only support fixed-size observations.

Related errors

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