{"record":{"id":"534e89f0df89e6ea","repo":"Unity-Technologies/ml-agents","slug":"visual-observation-resolution-width-x-height-i","errorCode":null,"errorMessage":"Visual observation resolution ({width}x{height}) is too small forthe provided EncoderType ({vis_encoder_type.value}). The min dimension is {min_res}","messagePattern":"Visual observation resolution \\((.+?)x(.+?)\\) is too small forthe provided EncoderType \\((.+?)\\)\\. The min dimension is (.+?)","errorType":"exception","errorClass":"UnityTrainerException","httpStatus":null,"severity":"error","filePath":"ml-agents/mlagents/trainers/torch_entities/utils.py","lineNumber":141,"sourceCode":"\n    @staticmethod\n    def get_encoder_for_type(encoder_type: EncoderType) -> nn.Module:\n        ENCODER_FUNCTION_BY_TYPE = {\n            EncoderType.SIMPLE: SimpleVisualEncoder,\n            EncoderType.NATURE_CNN: NatureVisualEncoder,\n            EncoderType.RESNET: ResNetVisualEncoder,\n            EncoderType.MATCH3: SmallVisualEncoder,\n            EncoderType.FULLY_CONNECTED: FullyConnectedVisualEncoder,\n        }\n        return ENCODER_FUNCTION_BY_TYPE.get(encoder_type)\n\n    @staticmethod\n    def _check_resolution_for_encoder(\n        height: int, width: int, vis_encoder_type: EncoderType\n    ) -> None:\n        min_res = ModelUtils.MIN_RESOLUTION_FOR_ENCODER[vis_encoder_type]\n        if height < min_res or width < min_res:\n            raise UnityTrainerException(\n                f\"Visual observation resolution ({width}x{height}) is too small for\"\n                f\"the provided EncoderType ({vis_encoder_type.value}). The min dimension is {min_res}\"\n            )\n\n    @staticmethod\n    def get_encoder_for_obs(\n        obs_spec: ObservationSpec,\n        normalize: bool,\n        h_size: int,\n        attention_embedding_size: int,\n        vis_encode_type: EncoderType,\n    ) -> Tuple[nn.Module, int]:\n        \"\"\"\n        Returns the encoder and the size of the appropriate encoder.\n        :param shape: Tuples that represent the observation dimension.\n        :param normalize: Normalize all vector inputs.\n        :param h_size: Number of hidden units per layer excluding attention layers.\n        :param attention_embedding_size: Number of hidden units per attention layer.","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents/mlagents/trainers/torch_entities/utils.py#L123-L159","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Increase the camera/RenderTexture sensor resolution in Unity to at least the encoder minimum (e.g. 84x84 for nature_cnn is typical)","Choose an encoder with a lower minimum (e.g. resnet requires 15, match3 5) in trainer config vis_encode_type","Set CameraSensorComponent width/height to >= min_res programmatically before training","Downscale later layers instead of the sensor if latency matters, keeping the sensor at min resolution"],"exampleFix":"// before (config)\nvis_encode_type: nature_cnn  # min 36px, camera is 32x32\n// after\nvis_encode_type: resnet  # min 15px, works with 32x32\n# or increase camera to 84x84 in Unity","handlingStrategy":"validation","validationCode":"from mlagents.trainers.torch_entities.utils import ModelUtils\nfrom mlagents.trainers.settings import EncoderType\nmin_res = ModelUtils.MIN_RESOLUTION_FOR_ENCODER[EncoderType.NATURE_CNN]\nassert height >= min_res and width >= min_res, f\"Camera must be >= {min_res}px for this encoder\"","typeGuard":"def resolution_ok(height: int, width: int, encoder) -> bool:\n    m = ModelUtils.MIN_RESOLUTION_FOR_ENCODER[encoder]\n    return height >= m and width >= m","tryCatchPattern":"from mlagents.trainers.exception import UnityTrainerException\ntry:\n    ModelUtils._check_resolution_for_encoder(h, w, enc)\nexcept UnityTrainerException as e:\n    logger.error(str(e))\n    raise SystemExit(\"Increase camera resolution or change vis_encode_type\")","preventionTips":["Keep camera sensors at >= 84x84 when using nature_cnn","Check MIN_RESOLUTION_FOR_ENCODER before changing vis_encode_type","Set sensor size programmatically so config and sensor agree"],"tags":["python","mlagents","visual-observations","resolution","config"],"backgroundTag":"visual-resolution-too-small","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}