Unity-Technologies/ml-agents · error · UnityAgentsException

When using compression type {m_CompressionType} the data val

Error message

When using compression type {m_CompressionType} the data value has to be normalized between 0-1. Received value[{dataValues[j]}] for {detectedObject.name}

What it means

When the grid sensor uses a compression type (e.g. PNG), the per-cell data written by DetectableObjects must be normalized to [0, 1] because the values are later packed into a texture/color channels. ValidateValues throws if any value written for a detected object falls outside 0-1.

Source

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

        protected internal virtual ProcessCollidersMethod GetProcessCollidersMethod()
        {
            return ProcessCollidersMethod.ProcessClosestColliders;
        }

        /// <summary>
        /// If using PNG compression, check if the values are normalized.
        /// </summary>
        void ValidateValues(float[] dataValues, GameObject detectedObject)
        {
            if (m_CompressionType != SensorCompressionType.PNG)
            {
                return;
            }

            for (int j = 0; j < dataValues.Length; j++)
            {
                if (dataValues[j] < 0 || dataValues[j] > 1)
                    throw new UnityAgentsException($"When using compression type {m_CompressionType} the data value has to be normalized between 0-1. " +
                        $"Received value[{dataValues[j]}] for {detectedObject.name}");
            }
        }

        /// <summary>
        /// Collect data from the detected object if a detectable tag is matched.
        /// </summary>
        internal void ProcessDetectedObject(GameObject detectedObject, int cellIndex)
        {
            Profiler.BeginSample("GridSensor.ProcessDetectedObject");
            for (var i = 0; i < m_DetectableTags.Length; i++)
            {
                if (!ReferenceEquals(detectedObject, null) && detectedObject.CompareTag(m_DetectableTags[i]))
                {
                    if (GetProcessCollidersMethod() == ProcessCollidersMethod.ProcessAllColliders)
                    {
                        Array.Copy(m_PerceptionBuffer, cellIndex * m_CellObservationSize, m_CellDataBuffer, 0, m_CellObservationSize);
                    }

View on GitHub (pinned to 3ecb446f75)

Solutions

Normalize all values returned by GetObjectData() to the [0,1] range (e.g. divide by max value or use Mathf.Clamp01 if clamping is acceptable)
Set the sensor's compression type to None if you need unbounded raw values (larger payloads)
Pre-scale data in the subclass: value / maxValue before returning the dataValues array
Check for negative sources (velocities, signed angles) and remap them, e.g. (v + 1) / 2 for [-1,1] inputs

Example fix

// before
float[] data = { distance }; // distance can be 0..100, compression=PNG
// after
float[] data = { Mathf.Clamp01(distance / maxDetectionDistance) };

Defensive patterns

Strategy: validation

Validate before calling

// Unity C#: before returning cell data in GetObjectData
for (int i = 0; i < dataValues.Length; i++)
{
    if (dataValues[i] < 0f || dataValues[i] > 1f)
        dataValues[i] = Mathf.Clamp01(dataValues[i]); // or normalize by max
}

Try / catch

try
{
    ProcessDetectedObject(hit.collider.gameObject);
}
catch (UnityAgentsException e) when (e.Message.Contains("normalized between 0-1"))
{
    Debug.LogError("Cell data not in [0,1] while compression is enabled: " + e.Message);
}

Prevention

Normalize values by a known max before returning them from GetObjectData()
Use CompressionType.None if raw unbounded values are required
Unit-test GetObjectData() outputs to assert range [0,1] when compression is on

When it happens

Trigger: A custom GridSensorBase subclass's GetObjectData() returning raw values >1 or <0 (e.g. counts, world-space distances, byte-valued 0-255 data) while CompressionType is not None; returning negative values such as signed velocities.

Common situations: Feeding raw distances or hit counts as cell data and switching compression on for bandwidth; porting sensor code from None to PNG compression without rescaling; passing color values as 0-255 ints instead of 0-1 floats.

Related errors

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