{"record":{"id":"79bcb2002ae664b1","repo":"Unity-Technologies/ml-agents","slug":"the-actions-in-demonstration-do-not-match-the-p","errorCode":null,"errorMessage":"The actions {} in demonstration do not match the policy's {}.","messagePattern":"The actions (.+?) in demonstration do not match the policy's (.+?)\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"ml-agents/mlagents/trainers/demo_loader.py","lineNumber":119,"sourceCode":"    return demo_processed_buffer\n\n\n@timed\ndef demo_to_buffer(\n    file_path: str, sequence_length: int, expected_behavior_spec: BehaviorSpec = None\n) -> Tuple[BehaviorSpec, AgentBuffer]:\n    \"\"\"\n    Loads demonstration file and uses it to fill training buffer.\n    :param file_path: Location of demonstration file (.demo).\n    :param sequence_length: Length of trajectories to fill buffer.\n    :return:\n    \"\"\"\n    behavior_spec, info_action_pair, _ = load_demonstration(file_path)\n    demo_buffer = make_demo_buffer(info_action_pair, behavior_spec, sequence_length)\n    if expected_behavior_spec:\n        # check action dimensions in demonstration match\n        if behavior_spec.action_spec != expected_behavior_spec.action_spec:\n            raise RuntimeError(\n                \"The actions {} in demonstration do not match the policy's {}.\".format(\n                    behavior_spec.action_spec, expected_behavior_spec.action_spec\n                )\n            )\n        # check observations match\n        if len(behavior_spec.observation_specs) != len(\n            expected_behavior_spec.observation_specs\n        ):\n            raise RuntimeError(\n                \"The demonstrations do not have the same number of observations as the policy.\"\n            )\n        else:\n            for i, (demo_obs, policy_obs) in enumerate(\n                zip(\n                    behavior_spec.observation_specs,\n                    expected_behavior_spec.observation_specs,\n                )\n            ):","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents/mlagents/trainers/demo_loader.py#L101-L137","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-record demonstrations with the current build so the action spec matches the policy","Verify the behavior name and action spec of the .demo file (ActionSpec: continuous_size, discrete branches) against the environment","Load the matching environment version the demos were recorded from","If intentional, update the environment's action space instead of the demo"],"exampleFix":"// before\ndemo_to_buffer('old_demos.demo', 128, current_behavior_spec)  # specs differ\n// after\n# re-record demos in the current environment\nbehavior_spec, pairs, _ = load_demonstration('new_demos.demo')\nassert behavior_spec.action_spec == current_behavior_spec.action_spec\ndemo_buffer = demo_to_buffer('new_demos.demo', 128, current_behavior_spec)","handlingStrategy":"validation","validationCode":"from mlagents.trainers.demo_loader import load_demonstration\nbehavior_spec, _, _ = load_demonstration(demo_path)\nif behavior_spec.action_spec != expected_behavior_spec.action_spec:\n    raise SystemExit(\n        f\"Demo {demo_path} action_spec {behavior_spec.action_spec} != \"\n        f\"policy {expected_behavior_spec.action_spec}; re-record demos\"\n    )","typeGuard":"def demo_action_spec_matches(demo_spec, expected_spec) -> bool:\n    return demo_spec.action_spec == expected_spec.action_spec","tryCatchPattern":"try:\n    demo_buffer = demo_to_buffer(demo_path, sequence_length, expected_behavior_spec)\nexcept RuntimeError as e:\n    if 'do not match' in str(e):\n        print(f\"Re-record demos: {e}\")\n    raise","preventionTips":["Record demonstrations with the exact environment build/action space used for training","Compare ActionSpec (continuous_size, discrete branches) of .demo files against the BehaviorSpec before training","Keep demo files versioned alongside the environment version that produced them"],"tags":["runtimeerror","ml-agents","demonstrations","action-space-mismatch"],"backgroundTag":"behavior-spec-mismatch","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}