Unity-Technologies/ml-agents · error · UnityObservationException

Compressed observation and its mapping had different number

Error message

Compressed observation and its mapping had different number of channels - observation had {len(image_arrays)} channels but its mapping had {len(mappings)} channels

What it means

UnityObservationException thrown by _process_images_mapping when the number of decompressed image channels (from the compressed observation payload) differs from the number of entries in compressed_channel_mapping sent by Unity. The mapping array and the image stack must be the same length so each channel can be reassembled.

Source

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

            image_fp.offset = new_offset
        except ValueError:
            # Didn't find the header, so must be at the end.
            break

    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)

View on GitHub (pinned to 3ecb446f75)

Solutions

  1. Verify the com.unity.ml-agents package version in Unity matches the ml-agents-envs Python package version and upgrade both to the same release.
  2. Rebuild the Unity executable after any change to agents/cameras so observations and channel mappings stay consistent.
  3. Reduce observation complexity (e.g. grayscale) to rule out custom sensor issues, then re-enable components to isolate the mismatching source.

Example fix

// before
# Unity env built from an older/ml-agents mismatched version
# after
# pip install mlagents==0.30.0 mlagents-envs==0.30.0 and rebuild the executable with matching com.unity.ml-agents 0.30.0
Defensive patterns

Strategy: try-catch

Try / catch

from mlagents_envs.exception import UnityObservationException

try:
    env.step()
except UnityObservationException as e:
    print("Observation/channel mapping mismatch:", e)
    env.close()
    env = UnityEnvironment(file_name=env_path)  # relaunch with matched versions

Prevention

When it happens

Trigger: process_pixels receiving compressed_data whose decompressed channel count != len(compressed_channel_mapping) — i.e. Unity sent a channel mapping inconsistent with the compressed observation.

Common situations: Mismatched Unity/Python ml-agents versions producing inconsistent observation protos; custom or modified Unity observation code emitting wrong channel mappings; corrupted serialization of the message.

Related errors

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