Unity-Technologies/ml-agents · error · UnityTrainerException

Visual observation resolution ({width}x{height}) is too smal

Error message

Visual observation resolution ({width}x{height}) is too small forthe provided EncoderType ({vis_encoder_type.value}). The min dimension is {min_res}

What it means

ModelUtils._check_resolution_for_encoder raises UnityTrainerException when a visual observation's width or height is smaller than the minimum resolution required by the chosen encoder type (e.g. NATURE_CNN needs 36, SIMPLE 20, RESNET 15, MATCH3 5). Convolutional encoders pool the input several times, so smaller images would collapse to zero spatial size.

Source

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

    @staticmethod
    def get_encoder_for_type(encoder_type: EncoderType) -> nn.Module:
        ENCODER_FUNCTION_BY_TYPE = {
            EncoderType.SIMPLE: SimpleVisualEncoder,
            EncoderType.NATURE_CNN: NatureVisualEncoder,
            EncoderType.RESNET: ResNetVisualEncoder,
            EncoderType.MATCH3: SmallVisualEncoder,
            EncoderType.FULLY_CONNECTED: FullyConnectedVisualEncoder,
        }
        return ENCODER_FUNCTION_BY_TYPE.get(encoder_type)

    @staticmethod
    def _check_resolution_for_encoder(
        height: int, width: int, vis_encoder_type: EncoderType
    ) -> None:
        min_res = ModelUtils.MIN_RESOLUTION_FOR_ENCODER[vis_encoder_type]
        if height < min_res or width < min_res:
            raise UnityTrainerException(
                f"Visual observation resolution ({width}x{height}) is too small for"
                f"the provided EncoderType ({vis_encoder_type.value}). The min dimension is {min_res}"
            )

    @staticmethod
    def get_encoder_for_obs(
        obs_spec: ObservationSpec,
        normalize: bool,
        h_size: int,
        attention_embedding_size: int,
        vis_encode_type: EncoderType,
    ) -> Tuple[nn.Module, int]:
        """
        Returns the encoder and the size of the appropriate encoder.
        :param shape: Tuples that represent the observation dimension.
        :param normalize: Normalize all vector inputs.
        :param h_size: Number of hidden units per layer excluding attention layers.
        :param attention_embedding_size: Number of hidden units per attention layer.

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Increase the camera/RenderTexture sensor resolution in Unity to at least the encoder minimum (e.g. 84x84 for nature_cnn is typical)
2. Choose an encoder with a lower minimum (e.g. resnet requires 15, match3 5) in trainer config vis_encode_type
3. Set CameraSensorComponent width/height to >= min_res programmatically before training
4. Downscale later layers instead of the sensor if latency matters, keeping the sensor at min resolution

Example fix

// before (config)
vis_encode_type: nature_cnn  # min 36px, camera is 32x32
// after
vis_encode_type: resnet  # min 15px, works with 32x32
# or increase camera to 84x84 in Unity

from mlagents.trainers.torch_entities.utils import ModelUtils
from mlagents.trainers.settings import EncoderType
min_res = ModelUtils.MIN_RESOLUTION_FOR_ENCODER[EncoderType.NATURE_CNN]
assert height >= min_res and width >= min_res, f"Camera must be >= {min_res}px for this encoder"

def resolution_ok(height: int, width: int, encoder) -> bool:
    m = ModelUtils.MIN_RESOLUTION_FOR_ENCODER[encoder]
    return height >= m and width >= m

from mlagents.trainers.exception import UnityTrainerException
try:
    ModelUtils._check_resolution_for_encoder(h, w, enc)
except UnityTrainerException as e:
    logger.error(str(e))
    raise SystemExit("Increase camera resolution or change vis_encode_type")

When it happens

Trigger: Creating input processors (create_input_processors) with a camera/visual observation whose dimensions are below ModelUtils.MIN_RESOLUTION_FOR_ENCODER for the configured vis_encode_type, e.g. a 32x32 camera with encoder_type: nature_cnn.

Common situations: Using small CameraSensorComponent sizes (like 20x20 or 32x32) with the default nature_cnn encoder; using match3 encoder with tiny grid visuals; changing encoder type in YAML without checking camera resolution.

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.
• Unsupported Sensor with specs {obs_spec}

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