Unity-Technologies/ml-agents · error · ValueError

The path provided is not a '.demo' file.

Error message

The path provided is not a '.demo' file.

What it means

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.

Source

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

                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]
    elif os.path.isdir(path):
        paths = [
            os.path.join(path, name)
            for name in os.listdir(path)
            if name.endswith(".demo")
        ]
        if not paths:
            raise ValueError("There are no '.demo' files in the provided directory.")
        return paths
    else:
        raise FileNotFoundError(
            f"The demonstration file or directory {path} does not exist."
        )


@timed
def load_demonstration(

View on GitHub (pinned to 3ecb446f75)

Solutions

  1. Point the path at the actual '.demo' file (not its .meta sibling or another artifact).
  2. Rename the demonstration file so it has the '.demo' extension if it was saved without one.
  3. If pointing at a directory, pass the directory path instead and let ML-Agents collect the '.demo' files inside.

Example fix

// before
trainer_config.demo_path = "demos/my_demo.demo.meta"
// after
trainer_config.demo_path = "demos/my_demo.demo"
Defensive patterns

Strategy: validation

Validate before calling

import os
path = "demos/my_demo.demo"
if os.path.isfile(path) and not path.endswith(".demo"):
    raise ValueError("demo_path must point to a .demo file")

Type guard

def is_demo_file(path: str) -> bool:
    return os.path.isfile(path) and path.endswith(".demo")

Try / catch

try:
    demo_spec, pairs, _ = load_demonstration(path)
except ValueError as e:
    if "not a '.demo' file" in str(e):
        path = path.replace(".meta", "")
        demo_spec, pairs, _ = load_demonstration(path)
    else:
        raise

Prevention

When it happens

Trigger: 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'.

Common situations: 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.

Related errors

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