Unity-Technologies/ml-agents · error · FileNotFoundError

The demonstration file or directory {path} does not exist.

Error message

The demonstration file or directory {path} does not exist.

What it means

get_demo_files raises this FileNotFoundError when the provided path is neither an existing file nor an existing directory, i.e. the demonstration path does not exist on disk. It is the standard 'bad path' guard before any parsing is attempted.

Source

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

    :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(
    file_path: str,
) -> Tuple[BehaviorSpec, List[AgentInfoActionPairProto], int]:
    """
    Loads and parses a demonstration file.
    :param file_path: Location of demonstration file (.demo).
    :return: BrainParameter and list of AgentInfoActionPairProto containing demonstration data.
    """

    # First 32 bytes of file dedicated to meta-data.
    file_paths = get_demo_files(file_path)
    behavior_spec = None
    brain_param_proto = None

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Check the path exists with os.path.exists and fix any typos in demo_path.
2. Use an absolute path (os.path.abspath) in the trainer config to avoid working-directory surprises.
3. Re-record or re-copy the demonstration file if it was deleted or never mounted into the environment/container.

Example fix

// before
trainer_config.demo_path = "demo/demost3.record"  # wrong name
// after
trainer_config.demo_path = os.path.abspath("demo/demonstrations/demo.demo")

import os
path = os.path.abspath(trainer_config["demo_path"])
if not os.path.exists(path):
    raise FileNotFoundError(f"demo_path does not exist: {path}")

def demo_path_exists(path: str) -> bool:
    return os.path.exists(os.path.abspath(path))

try:
    demo_spec, pairs, _ = load_demonstration(demo_path)
except FileNotFoundError as e:
    logger.error(f"Demo path not found: {demo_path}; check working directory and spelling")
    raise SystemExit(1)

When it happens

Trigger: Calling load_demonstration / demo_to_buffer with a path that does not exist, e.g. 'demos/typo_demo.demo', a deleted file, or a path with wrong case on a case-sensitive filesystem.

Common situations: Typo in demo_path in the trainer YAML; running training from a different working directory so relative paths resolve incorrectly; demo files removed during cleanup or not copied into a Docker image.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• The path provided is not a '.demo' file.
• There are no '.demo' files in the provided directory.
• Couldn't launch the {file_name} environment. Provided filena
• Config file could not be found at {abs_path}.
• The actions {} in demonstration do not match the policy's {}

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