Unity-Technologies/ml-agents · error · UnityAgentsException

shape and dimensionProperties must have the same length.

Error message

shape and dimensionProperties must have the same length.

What it means

The private ObservationSpec constructor requires the shape array and the dimensionProperties array to describe the same tensor, so their lengths must match. A length mismatch means one array was updated without the other, and the spec would be internally inconsistent, so it throws immediately.

Source

Thrown at com.unity.ml-agents/Runtime/Sensors/ObservationSpec.cs:131

        /// Create a general ObservationSpec from the shape, dimension properties, and observation type.
        /// </summary>
        /// <remarks>
        /// Note that not all combinations of DimensionProperty may be supported by the trainer.
        /// shape and dimensionProperties must have the same size.
        /// </remarks>
        /// <param name="shape">Shape</param>
        /// <param name="dimensionProperties">Dimension properties</param>
        /// <param name="observationType">Observation type</param>
        /// <exception cref="UnityAgentsException">Unity agents exception</exception>
        public ObservationSpec(
            InplaceArray<int> shape,
            InplaceArray<DimensionProperty> dimensionProperties,
            ObservationType observationType = ObservationType.Default
        )
        {
            if (shape.Length != dimensionProperties.Length)
            {
                throw new UnityAgentsException("shape and dimensionProperties must have the same length.");
            }
            m_Shape = shape;
            m_DimensionProperties = dimensionProperties;
            m_ObservationType = observationType;
        }
    }
}

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Pass dimensionProperties with exactly the same number of entries as shape, one DimensionProperty per dimension
2. Use a helper like InplaceArray.Empty<DimensionProperty>() only when shape is also empty; otherwise fill entries (e.g. DimensionProperty.NoneSI) for each dimension
3. Prefer the built-in factory methods (ObservationSpec.Vector, .Visual, .Default) instead of constructing specs manually
4. Add a debug check on array lengths at your sensor construction site

Example fix

// before
ObservationSpec.MakeSpec(new[] { 3, 4 }, new[] { DimensionProperty.NoneSI });
// after
ObservationSpec.MakeSpec(new[] { 3, 4 }, new[] { DimensionProperty.NoneSI, DimensionProperty.NoneSI });

// Unity C#: before building the spec
if (shape.Length != dimensionProperties.Length)
{
    Debug.LogError($"shape ({shape.Length}) and dimensionProperties ({dimensionProperties.Length}) must match");
}

try
{
    var spec = ObservationSpec.MakeSpec(shape, dimensionProperties);
}
catch (UnityAgentsException e) when (e.Message.Contains("same length"))
{
    Debug.LogError("Spec arrays mismatched: " + e.Message);
}

When it happens

Trigger: Calling ObservationSpec.MakeSpec(shape, dimensionProperties) with arrays of different lengths; hand-building a spec where shape has 3 entries but dimensionProperties has 2 (or vice versa).

Common situations: Custom sensor authors extending ObservationSpec with per-dimension properties; editing shape rank (e.g. adding a batch or time dimension) without extending the properties array; copy-pasted spec code with mismatched edits.

Related errors

• {failedCheck.Message}
• The BufferSensor was expecting an observation of size {m_Obs
• Index out of bounds, expected a number between 0 and {Length
• Enumerator not started.
• Enumerator has reached the end already.

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