What causes "Sensor {sensor.GetName()} have an invalid rank {rank}" in Unity-Technologies/ml-agents?

Reshape the sensor's observation to rank 3 or less (e.g. flatten extra dimensions into the channel or height/width axes)

Unity-Technologies/ml-agents · error · UnityAgentsException

Sensor {sensor.GetName()} have an invalid rank {rank}

Error message

Sensor {sensor.GetName()} have an invalid rank {rank}

What it means

TensorGenerator.InitializeObservations maps each sensor to an observation generator based on the sensor's observation rank. Only ranks 1 (vector), 2, and 3 are supported; any other rank hits the default case and throws. The message names the offending sensor and its rank.

Source

Thrown at com.unity.ml-agents/Runtime/Inference/TensorGenerator.cs:133

                            }
                            obsGen = vecObsGen;
                            obsGenName = TensorNames.VectorObservationPlaceholder;
                            break;
                        case 2:
                            // If the tensor is of rank 2, we use the index of the sensor
                            // to create the name
                            obsGen = new ObservationGenerator();
                            obsGenName = TensorNames.GetObservationName(sensorIndex);
                            break;
                        case 3:
                            // If the tensor is of rank 3, we use the "visual observation
                            // index", which only counts the rank 3 sensors
                            obsGen = new ObservationGenerator();
                            obsGenName = TensorNames.GetVisualObservationName(visIndex);
                            visIndex++;
                            break;
                        default:
                            throw new UnityAgentsException(
                                $"Sensor {sensor.GetName()} have an invalid rank {rank}");
                    }
                    obsGen.AddSensorIndex(sensorIndex);
                    m_Dict[obsGenName] = obsGen;
                }
            }

            if (m_ApiVersion == (int)SentisModelParamLoader.ModelApiVersion.MLAgents2_0)
            {
                for (var sensorIndex = 0; sensorIndex < sensors.Count; sensorIndex++)
                {
                    var obsGen = new ObservationGenerator();
                    var obsGenName = TensorNames.GetObservationName(sensorIndex);
                    obsGen.AddSensorIndex(sensorIndex);
                    m_Dict[obsGenName] = obsGen;
                }
            }
        }

View on GitHub (pinned to 3ecb446f75)

Solutions

Reshape the sensor's observation to rank 3 or less (e.g. flatten extra dimensions into the channel or height/width axes)
Ensure ObservationSpec dimensions are non-empty and the spec matches what the model was trained with
Split the observation into multiple sensors if the data is genuinely 4D

Example fix

// before
var spec = ObservationSpec.Visual(4, 8, 8, 3); // rank 4
// after
var spec = ObservationSpec.Visual(8, 8, 12); // merge 4 frames into channels, rank 3

Defensive patterns

Strategy: validation

Validate before calling

foreach (var sensor in sensors)
{
    int rank = sensor.GetObservationSpec().Rank();
    if (rank < 1 || rank > 3) throw new InvalidOperationException($"Sensor {sensor.GetName()} rank {rank} unsupported for inference");
}

Type guard

bool IsInferenceCompatibleRank(ISensor s) { var r = s.GetObservationSpec().Rank(); return r >= 1 && r <= 3; }

Try / catch

try { modelRunner.InitializeObservations(infos, ...); }
catch (UnityAgentsException e) when (e.Message.Contains("invalid rank"))
{ Debug.LogError($"Reshape sensor observation to rank <= 3: {e.Message}"); }

Prevention

Keep sensor ObservationSpec rank at 1-3 (vector, 2D, or 3D image)
Flatten or merge higher-dimensional data into channels before exposing it as an observation
Test custom sensors through a ModelRunner early in development

When it happens

Trigger: A sensor's GetObservationSpec() returns a shape with rank 0 or rank >= 4; reached when a ModelRunner initializes its observation generators.

Common situations: Custom sensors returning multi-dimensional (4+) observation specs that the inference path doesn't support; buggy observation spec construction (empty dimensions); using heuristics-only specs that don't fit inference expectations.

Related errors

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