{"record":{"id":"a9102cc4e7258d02","repo":"Unity-Technologies/ml-agents","slug":"invalid-compressed-channel-mapping-the-mapping-m","errorCode":null,"errorMessage":"Invalid Compressed Channel Mapping: the mapping {mappings} does not have the correct format.","messagePattern":"Invalid Compressed Channel Mapping: the mapping (.+?) does not have the correct format\\.","errorType":"exception","errorClass":"UnityObservationException","httpStatus":null,"severity":"error","filePath":"ml-agents-envs/mlagents_envs/rpc_utils.py","lineNumber":155,"sourceCode":"    if mappings is not None and len(mappings) > 0:\n        return _process_images_mapping(image_arrays, mappings)\n    else:\n        return _process_images_num_channels(image_arrays, expected_channels)\n\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","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents-envs/mlagents_envs/rpc_utils.py#L137-L173","documentation":"UnityObservationException thrown by _process_images_mapping when the set of non-negative values in compressed_channel_mapping doesn't form a dense 0..max sequence — i.e. some channel index in 0..max(mappings) is never assigned. Unity's channel mapping must map each compressed channel to every uncompressed index exactly (with -1 meaning unused).","triggerScenarios":"Receiving a compressed_channel_mapping like [0, 2, 2] where index 1 is missing, or any mapping whose unique positive values count != max(mappings)+1.","commonSituations":"Version mismatch between Unity package and mlagents-envs producing a mapping format change; corrupted or hand-edited observation messages; custom Unity sensors writing mappings directly.","solutions":["Align com.unity.ml-agents (Unity) and mlagents-envs (Python) to the exact same release version.","Rebuild the Unity executable with the matching package to eliminate stale serialized mapping logic.","If you control Unity-side code, ensure every uncompressed channel index 0..N-1 appears exactly once in the mapping."],"exampleFix":"// before\n# mapping from Unity: [0, 2, 2]  (channel 1 never mapped)\n// after\n# rebuild Unity env with matching package so it emits a dense mapping, e.g. [0, 1, 2]","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 \"Invalid Compressed Channel Mapping\" in str(e):\n        env.close()\n        env = UnityEnvironment(file_name=env_path)  # relaunch with matched versions","preventionTips":["Pin com.unity.ml-agents and mlagents-envs versions together (upgrade in lockstep).","Rebuild the Unity executable after package upgrades.","Avoid custom modifications to the compressed channel mapping pipeline."],"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"}