{"record":{"id":"afbd3b17db25833c","repo":"Unity-Technologies/ml-agents","slug":"the-path-provided-is-not-a-demo-file","errorCode":null,"errorMessage":"The path provided is not a '.demo' file.","messagePattern":"The path provided is not a '\\.demo' file\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"ml-agents/mlagents/trainers/demo_loader.py","lineNumber":156,"sourceCode":"                if demo_obs.shape != policy_obs.shape:\n                    raise RuntimeError(\n                        f\"The shape {demo_obs} for observation {i} in demonstration \\\n                        do not match the policy's {policy_obs}.\"\n                    )\n    return behavior_spec, demo_buffer\n\n\ndef get_demo_files(path: str) -> List[str]:\n    \"\"\"\n    Retrieves the demonstration file(s) from a path.\n    :param path: Path of demonstration file or directory.\n    :return: List of demonstration files\n\n    Raises errors if |path| is invalid.\n    \"\"\"\n    if os.path.isfile(path):\n        if not path.endswith(\".demo\"):\n            raise ValueError(\"The path provided is not a '.demo' file.\")\n        return [path]\n    elif os.path.isdir(path):\n        paths = [\n            os.path.join(path, name)\n            for name in os.listdir(path)\n            if name.endswith(\".demo\")\n        ]\n        if not paths:\n            raise ValueError(\"There are no '.demo' files in the provided directory.\")\n        return paths\n    else:\n        raise FileNotFoundError(\n            f\"The demonstration file or directory {path} does not exist.\"\n        )\n\n\n@timed\ndef load_demonstration(","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents/mlagents/trainers/demo_loader.py#L138-L174","documentation":"get_demo_files resolves a user-supplied path to a list of demonstration files. If the path points to an existing file but lacks the '.demo' extension, it raises this ValueError because ML-Agents only treats '.demo' files as recorded demonstrations. This guards against passing model checkpoints, config files, or other artifacts by mistake.","triggerScenarios":"Calling load_demonstration (or demo loading via trainer config demo_path) with a path to an existing file whose name does not end in '.demo', e.g. passing 'my_demo.demo.meta' or 'run1.onnx'.","commonSituations":"Passing the Unity-side '.meta' companion file by accident; renaming demo files to '.bytes' or '.json'; pointing at a checkpoint or summary file instead of the recording.","solutions":["Point the path at the actual '.demo' file (not its .meta sibling or another artifact).","Rename the demonstration file so it has the '.demo' extension if it was saved without one.","If pointing at a directory, pass the directory path instead and let ML-Agents collect the '.demo' files inside."],"exampleFix":"// before\ntrainer_config.demo_path = \"demos/my_demo.demo.meta\"\n// after\ntrainer_config.demo_path = \"demos/my_demo.demo\"","handlingStrategy":"validation","validationCode":"import os\npath = \"demos/my_demo.demo\"\nif os.path.isfile(path) and not path.endswith(\".demo\"):\n    raise ValueError(\"demo_path must point to a .demo file\")","typeGuard":"def is_demo_file(path: str) -> bool:\n    return os.path.isfile(path) and path.endswith(\".demo\")","tryCatchPattern":"try:\n    demo_spec, pairs, _ = load_demonstration(path)\nexcept ValueError as e:\n    if \"not a '.demo' file\" in str(e):\n        path = path.replace(\".meta\", \"\")\n        demo_spec, pairs, _ = load_demonstration(path)\n    else:\n        raise","preventionTips":["Never pass Unity .meta companion files as demo paths","Keep the '.demo' extension when renaming or copying recordings","Point configs at the .demo file itself, not the directory listing artifacts"],"tags":["ml-agents","file-path","demonstrations","valueerror"],"backgroundTag":"invalid-file-extension","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}