What causes "GridSensor only supports 2D grids." in Unity-Technologies/ml-agents?

Set the grid size Y component to 1, keeping detection in the XZ plane (e.g. Vector3(10, 1, 10))

Unity-Technologies/ml-agents · error · UnityAgentsException

GridSensor only supports 2D grids.

Error message

GridSensor only supports 2D grids.

What it means

GridSensorBase's constructor only accepts grid sizes whose Y dimension is 1, i.e. flat 2D grids in the XZ plane. A grid with Y != 1 (a 3D volume) has no supported implementation and is rejected at construction time before any observation is produced.

Source

Thrown at com.unity.ml-agents/Runtime/Sensors/GridSensorBase.cs:73

        /// <param name="detectableTags">Tags to be detected by the sensor</param>
        /// <param name="compression">Compression type</param>
        public GridSensorBase(
            string name,
            Vector3 cellScale,
            Vector3Int gridSize,
            string[] detectableTags,
            SensorCompressionType compression
        )
        {
            m_Name = name;
            m_CellScale = cellScale;
            m_GridSize = gridSize;
            m_DetectableTags = detectableTags;
            CompressionType = compression;

            if (m_GridSize.y != 1)
            {
                throw new UnityAgentsException("GridSensor only supports 2D grids.");
            }

            m_NumCells = m_GridSize.x * m_GridSize.z;
            m_CellObservationSize = GetCellObservationSize();
            m_ObservationSpec = ObservationSpec.Visual(m_CellObservationSize, m_GridSize.x, m_GridSize.z);
            m_PerceptionTexture = new Texture2D(m_GridSize.x, m_GridSize.z, TextureFormat.RGB24, false);

            ResetPerceptionBuffer();
        }

        /// <summary>
        /// The compression type used by the sensor.
        /// </summary>
        public SensorCompressionType CompressionType
        {
            get { return m_CompressionType; }
            set
            {

View on GitHub (pinned to 3ecb446f75)

Solutions

Set the grid size Y component to 1, keeping detection in the XZ plane (e.g. Vector3(10, 1, 10))
Move vertical detection into the detected-object filtering logic or cell data rather than extra grid layers
If 3D volumes are truly required, implement a custom SensorBase instead of GridSensorBase

Example fix

// before
new GridSensorBase("grid", cellScale, new Vector3(10, 5, 10), tags, compression);
// after
new GridSensorBase("grid", cellScale, new Vector3(10, 1, 10), tags, compression);

Defensive patterns

Strategy: validation

Validate before calling

// Unity C#: before constructing the sensor
if (gridSize.y != 1)
{
    Debug.LogError($"GridSensor requires gridSize.y == 1, got {gridSize.y}");
    gridSize = new Vector3(gridSize.x, 1, gridSize.z);
}

Try / catch

try
{
    var sensor = new GridSensorBase("grid", cellScale, gridSize, tags, compression);
}
catch (UnityAgentsException e) when (e.Message.Contains("only supports 2D grids"))
{
    Debug.LogError("Set grid size Y to 1: " + e.Message);
}

Prevention

Always set grid size Y to 1 (e.g. Vector3(10, 1, 10))
Handle vertical detection via filtering/cell data, not extra Y layers
Validate grid size in Awake before sensor construction

When it happens

Trigger: Constructing GridSensorBase (or subclass) with a gridSize Vector3 whose .y is not 1; configuring GridSensorComponent's GridSize Y field to a value other than 1 in the inspector.

Common situations: Attempting to build a 3D volumetric detection grid for flying/drone agents; copy-pasting a Vector3 size (e.g. (10, 5, 10)) meant for spatial bounds directly into grid size.

Related errors

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