Unity-Technologies/ml-agents · error · UnityTrainerException

Unsupported Sensor with specs {obs_spec}

Error message

Unsupported Sensor with specs {obs_spec}

What it means

ModelUtils.get_encoder_for_obs raises UnityTrainerException when an ObservationSpec matches none of the supported categories (visual with translational-equivariance dims, plain vector, or entity/variable-length). ML-Agents only knows how to build input processors for those observation shapes; anything else is unsupported.

Source

Thrown at ml-agents/mlagents/trainers/torch_entities/utils.py:186

            ModelUtils._check_resolution_for_encoder(
                shape[1], shape[2], vis_encode_type
            )
            return (visual_encoder_class(shape[1], shape[2], shape[0], h_size), h_size)
        # VECTOR
        if dim_prop in ModelUtils.VALID_VECTOR_PROP:
            return (VectorInput(shape[0], normalize), shape[0])
        # VARIABLE LENGTH
        if dim_prop in ModelUtils.VALID_VAR_LEN_PROP:
            return (
                EntityEmbedding(
                    entity_size=shape[1],
                    entity_num_max_elements=shape[0],
                    embedding_size=attention_embedding_size,
                ),
                0,
            )
        # OTHER
        raise UnityTrainerException(f"Unsupported Sensor with specs {obs_spec}")

    @staticmethod
    def create_input_processors(
        observation_specs: List[ObservationSpec],
        h_size: int,
        vis_encode_type: EncoderType,
        attention_embedding_size: int,
        normalize: bool = False,
    ) -> Tuple[nn.ModuleList, List[int]]:
        """
        Creates visual and vector encoders, along with their normalizers.
        :param observation_specs: List of ObservationSpec that represent the observation dimensions.
        :param action_size: Number of additional un-normalized inputs to each vector encoder. Used for
            conditioning network on other values (e.g. actions for a Q function)
        :param h_size: Number of hidden units per layer excluding attention layers.
        :param attention_embedding_size: Number of hidden units per attention layer.
        :param vis_encode_type: Type of visual encoder to use.
        :param unnormalized_inputs: Vector inputs that should not be normalized, and added to the vector

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Use a supported sensor type (CameraSensor, VectorSensor, or Entity sensor) that emits standard ObservationSpecs
2. Fix the custom sensor's observation spec (rank and DimensionProperty values) to match a supported pattern: visual = rank 3 with TRANSLATIONAL_EQUIVARIANCE on H/W, vector = rank 1 or [N,1]
3. Check mlagents version compatibility with the sensor package emitting the observation
4. Flatten/convert exotic observations into a VectorSensor in your Unity code before training

Example fix

// before (custom sensor spec)
obs_spec = ObservationSpec(shape=(4,4), dim_props=(NONE, NONE))  # rank-2, unsupported
// after
obs_spec = ObservationSpec(shape=(16,), dim_props=(NONE,))  # rank-1 vector, supported

from mlagents_envs.base_env import DimensionProperty
def supported(spec) -> bool:
    if len(spec.shape) == 3 and spec.dimension_property[1:] == (DimensionProperty.TRANSLATIONAL_EQUIVARIANCE,)*2:
        return True  # visual
    return len(spec.shape) in (1, 2)  # vector
assert all(supported(s) for s in behavior_spec.observation_specs)

def is_supported_obs_spec(spec) -> bool:
    dp = spec.dimension_property or (DimensionProperty.UNSPECIFIED,) * len(spec.shape)
    visual = len(spec.shape) == 3 and dp[1:] == (DimensionProperty.TRANSLATIONAL_EQUIVARIANCE, DimensionProperty.TRANSLATIONAL_EQUIVARIANCE)
    vector = len(spec.shape) == 1 or (len(spec.shape) == 2 and spec.shape[1] == 1)
    return visual or vector

try:
    processors = ModelUtils.create_input_processors(obs_specs, h, enc, norm)
except UnityTrainerException as e:
    logger.error(f"Unsupported observation: {e}")
    raise SystemExit("Replace the sensor emitting the unsupported ObservationSpec")

When it happens

Trigger: create_input_processors encountering an ObservationSpec whose dimension properties (e.g. unrecognized combinations of DimensionProperty.TRANSLATIONAL_EQUIVARIANCE/SEMANTIC/none) or rank do not match the visual, vector, or entity patterns it handles.

Common situations: Custom sensors emitting unusual observation shapes/DimensionProperty combinations; Unity sensors added from packages (e.g. Grid sensor) in versions where ML-Agents had no encoder for them; migrating environments to newer mlagents-envs with new dimension property values.

Related errors

• The trainer was unable to process any of the provided inputs
• The one of the goals uses variable length observations. This
• Trainer was unable to process any of the goals provided as i
• The schedule {self.schedule} is invalid.
• Visual observation resolution ({width}x{height}) is too smal

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