Unity-Technologies/ml-agents · error · UnityObservationException

Invalid Compressed Channel Mapping: the mapping {mappings} d

Error message

Invalid Compressed Channel Mapping: the mapping {mappings} does not have the correct format.

What it means

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).

Source

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

    if mappings is not None and len(mappings) > 0:
        return _process_images_mapping(image_arrays, mappings)
    else:
        return _process_images_num_channels(image_arrays, expected_channels)


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

View on GitHub (pinned to 3ecb446f75)

Solutions

  1. Align com.unity.ml-agents (Unity) and mlagents-envs (Python) to the exact same release version.
  2. Rebuild the Unity executable with the matching package to eliminate stale serialized mapping logic.
  3. If you control Unity-side code, ensure every uncompressed channel index 0..N-1 appears exactly once in the mapping.

Example fix

// before
# mapping from Unity: [0, 2, 2]  (channel 1 never mapped)
// after
# rebuild Unity env with matching package so it emits a dense mapping, e.g. [0, 1, 2]
Defensive patterns

Strategy: try-catch

Try / catch

from mlagents_envs.exception import UnityObservationException

try:
    env.step()
except UnityObservationException as e:
    if "Invalid Compressed Channel Mapping" in str(e):
        env.close()
        env = UnityEnvironment(file_name=env_path)  # relaunch with matched versions

Prevention

When it happens

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

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

Related errors

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