Unity-Technologies/ml-agents · error · RuntimeError

The actions {} in demonstration do not match the policy's {}

Error message

The actions {} in demonstration do not match the policy's {}.

What it means

demo_to_buffer compares the demonstration file's BehaviorSpec action spec against the expected spec of the policy being trained; if they differ (different action sizes, branch counts, or discrete/continuous type) it raises this RuntimeError. This prevents training on demos whose action space is incompatible with the current agent.

Source

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

    return demo_processed_buffer


@timed
def demo_to_buffer(
    file_path: str, sequence_length: int, expected_behavior_spec: BehaviorSpec = None
) -> Tuple[BehaviorSpec, AgentBuffer]:
    """
    Loads demonstration file and uses it to fill training buffer.
    :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,
                )
            ):

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Re-record demonstrations with the current build so the action spec matches the policy
2. Verify the behavior name and action spec of the .demo file (ActionSpec: continuous_size, discrete branches) against the environment
3. Load the matching environment version the demos were recorded from
4. If intentional, update the environment's action space instead of the demo

Example fix

// before
demo_to_buffer('old_demos.demo', 128, current_behavior_spec)  # specs differ
// after
# re-record demos in the current environment
behavior_spec, pairs, _ = load_demonstration('new_demos.demo')
assert behavior_spec.action_spec == current_behavior_spec.action_spec
demo_buffer = demo_to_buffer('new_demos.demo', 128, current_behavior_spec)

from mlagents.trainers.demo_loader import load_demonstration
behavior_spec, _, _ = load_demonstration(demo_path)
if behavior_spec.action_spec != expected_behavior_spec.action_spec:
    raise SystemExit(
        f"Demo {demo_path} action_spec {behavior_spec.action_spec} != "
        f"policy {expected_behavior_spec.action_spec}; re-record demos"
    )

def demo_action_spec_matches(demo_spec, expected_spec) -> bool:
    return demo_spec.action_spec == expected_spec.action_spec

try:
    demo_buffer = demo_to_buffer(demo_path, sequence_length, expected_behavior_spec)
except RuntimeError as e:
    if 'do not match' in str(e):
        print(f"Re-record demos: {e}")
    raise

When it happens

Trigger: Calling demo_to_buffer(file_path, sequence_length, expected_behavior_spec) where behavior_spec.action_spec != expected_behavior_spec.action_spec — typically inside imitation learning trainer init with a mismatched .demo file.

Common situations: Recording demos with an older/modified Unity environment whose action space changed, using a demo from a different environment/brain, or changing continuous action size or discrete branches after recording.

Related errors

• The demonstrations do not have the same number of observatio
• The shape {demo_obs} for observation {i} in demonstration
• 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/79bcb2002ae664b1. Report an issue: GitHub.