Unity-Technologies/ml-agents · error · RuntimeError

The shape {demo_obs} for observation {i} in demonstration

Error message

The shape {demo_obs} for observation {i} in demonstration                         do not match the policy's {policy_obs}.

What it means

When the number of observations matches, demo_to_buffer compares each observation spec's shape element-wise. This RuntimeError is thrown when demonstration observation i has a different shape (e.g. camera resolution or vector observation size) than the policy's corresponding observation. It prevents training on dimensionally incompatible demo data.

Source

Thrown at ml-agents/mlagents/trainers/demo_loader.py:139

                    behavior_spec.action_spec, expected_behavior_spec.action_spec
                )
            )
        # check observations match
        if len(behavior_spec.observation_specs) != len(
            expected_behavior_spec.observation_specs
        ):
            raise RuntimeError(
                "The demonstrations do not have the same number of observations as the policy."
            )
        else:
            for i, (demo_obs, policy_obs) in enumerate(
                zip(
                    behavior_spec.observation_specs,
                    expected_behavior_spec.observation_specs,
                )
            ):
                if demo_obs.shape != policy_obs.shape:
                    raise RuntimeError(
                        f"The shape {demo_obs} for observation {i} in demonstration \
                        do not match the policy's {policy_obs}."
                    )
    return behavior_spec, demo_buffer


def get_demo_files(path: str) -> List[str]:
    """
    Retrieves the demonstration file(s) from a path.
    :param path: Path of demonstration file or directory.
    :return: List of demonstration files

    Raises errors if |path| is invalid.
    """
    if os.path.isfile(path):
        if not path.endswith(".demo"):
            raise ValueError("The path provided is not a '.demo' file.")
        return [path]

View on GitHub (pinned to 3ecb446f75)

Solutions

Re-record the demonstration file with the observation shapes (resolution, vector size) matching the current training environment.
Align the training environment's observation shapes to the demo's shapes (e.g. set camera resolution to 84x84 in Behavior Parameters).
Inspect the demo's BrainParametersProto offline (load_demonstration returns behavior_spec) and diff shapes against BehaviorSpec before training.

Example fix

// before
behavior_parameters: camera_resolution: 64  # demo recorded at 84
// after
behavior_parameters: camera_resolution: 84  # matches demo recording

Defensive patterns

Strategy: validation

Validate before calling

demo_spec, _, _ = load_demonstration("demos/my_demo.demo")
for i, (d, p) in enumerate(zip(demo_spec.observation_specs, expected_behavior_spec.observation_specs)):
    assert d.shape == p.shape, f"obs {i}: demo {d.shape} != policy {p.shape}"

Type guard

def demo_obs_shapes_match(demo_spec, policy_spec):
    if len(demo_spec.observation_specs) != len(policy_spec.observation_specs):
        return False
    return all(d.shape == p.shape for d, p in zip(demo_spec.observation_specs, policy_spec.observation_specs))

Try / catch

try:
    demo_spec, demo_buffer = demo_to_buffer(path, expected_behavior_spec)
except RuntimeError as e:
    if "do not match the policy's" in str(e):
        logger.error("Align camera resolution / vector obs size between demo and env")
        raise SystemExit(1)
    raise

Prevention

Keep Behavior Parameters (camera resolution, grayscale, vector obs size) unchanged after recording demos
Store demos alongside the config that produced them
Diff demo vs policy observation shapes before starting imitation training

When it happens

Trigger: demo_to_buffer called with a demo whose observation spec shape differs from expected_behavior_spec's, e.g. demo recorded at 84x84 resolution while the training env uses 64x64, or vector observation size changed in the Brain/Behavior Parameters.

Common situations: Changing camera resolution or grayscale setting in Unity after recording demos; changing vector observation space size in Behavior Parameters; using a demo file from an older version of the project with different observation dimensions.

Related errors

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