Unity-Technologies/ml-agents · error · RuntimeError

The demonstrations do not have the same number of observatio

Error message

The demonstrations do not have the same number of observations as the policy.

What it means

demo_to_buffer validates that a recorded demonstration file's BehaviorSpec matches the behavior spec expected by the policy being trained. This RuntimeError is thrown when the number of observation specs in the demonstration differs from the number the policy has. ML-Aggers throws it early so training never starts on incompatible data.

Source

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

    :param file_path: Location of demonstration file (.demo).
    :param sequence_length: Length of trajectories to fill buffer.
    :return:
    """
    behavior_spec, info_action_pair, _ = load_demonstration(file_path)
    demo_buffer = make_demo_buffer(info_action_pair, behavior_spec, sequence_length)
    if expected_behavior_spec:
        # check action dimensions in demonstration match
        if behavior_spec.action_spec != expected_behavior_spec.action_spec:
            raise RuntimeError(
                "The actions {} in demonstration do not match the policy's {}.".format(
                    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]:

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Re-record the .demo demonstration file using the exact environment/scene configuration (same sensors and observations) as the training environment.
2. Verify the behavior spec of the demo against the policy with a quick script comparing len(observation_specs) before training.
3. If the extra observation is intentional, either re-record or regenerate the policy's behavior spec so both have the same observation count.

Example fix

// before: training with demos recorded from env with 2 sensors
trainer_config = {"demo_path": "old_demo.demo"}  # demo has 2 obs, policy has 1
// after: re-record demo in current env
trainer_config = {"demo_path": "new_demo.demo"}  # re-recorded with 1 obs

from mlagents.trainers.demo_loader import load_demonstration
demo_spec, _, _ = load_demonstration("demos/my_demo.demo")
assert len(demo_spec.observation_specs) == len(expected_behavior_spec.observation_specs), (
    "demo/policy observation count mismatch")

def demo_obs_count_matches(demo_spec, policy_spec):
    return len(demo_spec.observation_specs) == len(policy_spec.observation_specs)

try:
    demo_spec, demo_buffer = demo_to_buffer(path, expected_behavior_spec)
except RuntimeError as e:
    if "same number of observations" in str(e):
        logger.error("Re-record demos: obs count mismatch")
        raise SystemExit(1)
    raise

When it happens

Trigger: Calling demo_to_buffer (via __init__ of a trainer using demonstrations, e.g. through demo_path in trainer config) where behavior_spec.observation_specs and expected_behavior_spec.observation_specs have different lengths, e.g. the .demo file was recorded with a different number of sensors/cameras than the environment used for training.

Common situations: Adding or removing a camera/visual sensor or vector observation in the Unity scene after recording demos; loading a demo from a different environment build; mismatched sensor flags (e.g. recording had two RenderTexture sensors but training env has one).

Related errors

• The shape {demo_obs} for observation {i} in demonstration
• The actions {} in demonstration do not match the policy's {}
• The path provided is not a '.demo' file.
• There are no '.demo' files in the provided directory.
• The demonstration file or directory {path} does not exist.

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