{"record":{"id":"ae7d2ffb855d6e5c","repo":"Unity-Technologies/ml-agents","slug":"invalid-compressed-channel-mapping-the-mapping-ha","errorCode":null,"errorMessage":"Invalid Compressed Channel Mapping: the mapping has index larger than the total number of channels in observation - mapping index {max(mappings)} isinvalid for input observation with {len(image_arrays)} channels.","messagePattern":"Invalid Compressed Channel Mapping: the mapping has index larger than the total number of channels in observation - mapping index (.+?) isinvalid for input observation with (.+?) channels\\.","errorType":"exception","errorClass":"UnityObservationException","httpStatus":null,"severity":"error","filePath":"ml-agents-envs/mlagents_envs/rpc_utils.py","lineNumber":159,"sourceCode":"\n\ndef _process_images_mapping(image_arrays, mappings):\n    \"\"\"\n    Helper function for processing decompressed images with compressed channel mappings.\n    \"\"\"\n    image_arrays = np.concatenate(image_arrays, axis=0).transpose((0, 1, 2))\n\n    if len(mappings) != len(image_arrays):\n        raise UnityObservationException(\n            f\"Compressed observation and its mapping had different number of channels - \"\n            f\"observation had {len(image_arrays)} channels but its mapping had {len(mappings)} channels\"\n        )\n    if len({m for m in mappings if m > -1}) != max(mappings) + 1:\n        raise UnityObservationException(\n            f\"Invalid Compressed Channel Mapping: the mapping {mappings} does not have the correct format.\"\n        )\n    if max(mappings) >= len(image_arrays):\n        raise UnityObservationException(\n            f\"Invalid Compressed Channel Mapping: the mapping has index larger than the total \"\n            f\"number of channels in observation - mapping index {max(mappings)} is\"\n            f\"invalid for input observation with {len(image_arrays)} channels.\"\n        )\n\n    processed_image_arrays: List[np.array] = [[] for _ in range(max(mappings) + 1)]\n    for mapping_idx, img in zip(mappings, image_arrays):\n        if mapping_idx > -1:\n            processed_image_arrays[mapping_idx].append(img)\n\n    for i, img_array in enumerate(processed_image_arrays):\n        processed_image_arrays[i] = np.mean(img_array, axis=0)\n    img = np.stack(processed_image_arrays, axis=0)\n    return img\n\n\ndef _process_images_num_channels(image_arrays, expected_channels):\n    \"\"\"","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents-envs/mlagents_envs/rpc_utils.py#L141-L177","documentation":"UnityObservationException thrown by _process_images_mapping when max(compressed_channel_mapping) is greater than or equal to the number of decompressed channels, i.e. the mapping references a channel index that doesn't exist in the observation data.","triggerScenarios":"Receiving compressed data with, say, 3 decompressed channels but a mapping containing index 3+; mapping produced by an incompatible Unity/Python version pair or corrupted message.","commonSituations":"Stale Unity executable built with a different com.unity.ml-agents version than the Python side; custom sensors emitting incorrect mappings; message corruption over the gRPC channel.","solutions":["Match com.unity.ml-agents and mlagents-envs versions exactly and rebuild the Unity executable.","Verify with a known-good environment (e.g. a sample env) to confirm the issue is environment-specific.","Report/reproduce with a minimal Unity scene if a custom sensor or camera is involved."],"exampleFix":"// before\n# Python: mlagents-envs 0.23, Unity: com.unity.ml-agents 0.28 -> mapping index out of range\n// after\n# pip install mlagents-envs==0.28.0 to match the Unity package version","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"from mlagents_envs.exception import UnityObservationException\n\ntry:\n    env.step()\nexcept UnityObservationException as e:\n    if \"index larger than the total\" in str(e):\n        env.close()\n        env = UnityEnvironment(file_name=env_path)","preventionTips":["Match Unity/Python ml-agents versions exactly.","Rebuild the environment executable whenever the com.unity.ml-agents package updates.","Validate against a stock sample env after version changes."],"tags":["python","unity-ml-agents","observation","protocol-mismatch"],"backgroundTag":"observation-channel-mapping-mismatch","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}