Unity-Technologies/ml-agents · error · UnityObservationException

Invalid Compressed Channel Mapping: the mapping has index la

Error message

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.

What it means

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.

Source

Thrown at ml-agents-envs/mlagents_envs/rpc_utils.py:159


def _process_images_mapping(image_arrays, mappings):
    """
    Helper function for processing decompressed images with compressed channel mappings.
    """
    image_arrays = np.concatenate(image_arrays, axis=0).transpose((0, 1, 2))

    if len(mappings) != len(image_arrays):
        raise UnityObservationException(
            f"Compressed observation and its mapping had different number of channels - "
            f"observation had {len(image_arrays)} channels but its mapping had {len(mappings)} channels"
        )
    if len({m for m in mappings if m > -1}) != max(mappings) + 1:
        raise UnityObservationException(
            f"Invalid Compressed Channel Mapping: the mapping {mappings} does not have the correct format."
        )
    if max(mappings) >= len(image_arrays):
        raise UnityObservationException(
            f"Invalid Compressed Channel Mapping: the mapping has index larger than the total "
            f"number of channels in observation - mapping index {max(mappings)} is"
            f"invalid for input observation with {len(image_arrays)} channels."
        )

    processed_image_arrays: List[np.array] = [[] for _ in range(max(mappings) + 1)]
    for mapping_idx, img in zip(mappings, image_arrays):
        if mapping_idx > -1:
            processed_image_arrays[mapping_idx].append(img)

    for i, img_array in enumerate(processed_image_arrays):
        processed_image_arrays[i] = np.mean(img_array, axis=0)
    img = np.stack(processed_image_arrays, axis=0)
    return img


def _process_images_num_channels(image_arrays, expected_channels):
    """

View on GitHub (pinned to 3ecb446f75)

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.

Example fix

// before
# Python: mlagents-envs 0.23, Unity: com.unity.ml-agents 0.28 -> mapping index out of range
// after
# pip install mlagents-envs==0.28.0 to match the Unity package version

Defensive patterns

Strategy: try-catch

Try / catch

from mlagents_envs.exception import UnityObservationException

try:
    env.step()
except UnityObservationException as e:
    if "index larger than the total" in str(e):
        env.close()
        env = UnityEnvironment(file_name=env_path)

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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