Unity-Technologies/ml-agents · error · TrainerConfigError

Config file could not be found at {abs_path}.

Error message

Config file could not be found at {abs_path}.

What it means

mlagents-learn's load_config opens the YAML config file; if the OS reports an error (file missing, permission denied) it wraps it in a TrainerConfigError with the absolute path it tried. This is the standard 'config file not found' failure of the Unity ML-Agents trainer CLI.

Source

Thrown at ml-agents/mlagents/trainers/cli_utils.py:326

    torch_conf = argparser.add_argument_group(title="Torch Configuration")
    torch_conf.add_argument(
        "--torch-device",
        default=None,
        dest="device",
        action=DetectDefault,
        help='Settings for the default torch.device used in training, for example, "cpu", "cuda", or "cuda:0"',
    )
    return argparser


def load_config(config_path: str) -> Dict[str, Any]:
    try:
        with open(config_path) as data_file:
            return _load_config(data_file)
    except OSError:
        abs_path = os.path.abspath(config_path)
        raise TrainerConfigError(f"Config file could not be found at {abs_path}.")
    except UnicodeDecodeError:
        raise TrainerConfigError(
            f"There was an error decoding Config file from {config_path}. "
            f"Make sure your file is save using UTF-8"
        )


def _load_config(fp: TextIO) -> Dict[str, Any]:
    """
    Load the yaml config from the file-like object.
    """
    try:
        return yaml.safe_load(fp)
    except yaml.parser.ParserError as e:
        raise TrainerConfigError(
            "Error parsing yaml file. Please check for formatting errors. "
            "A tool such as http://www.yamllint.com/ can be helpful with this."
        ) from e

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Check the absolute path in the message and verify the file exists: ls <abs_path>
2. Pass an absolute path or run from the repo root, e.g. mlagents-learn config/ppo/3DBall.yaml --run-id=...
3. Fix file permissions or point to the correct file
4. If a directory was passed, specify the YAML file itself

Example fix

// before
mlagents-learn ./ppo_config.yaml --run-id=run1   # file not there
// after
mlagents-learn /abs/path/config/ppo/3DBall.yaml --run-id=run1

import os
path = config_path
if not os.path.isfile(path):
    raise SystemExit(f"Trainer config not found: {os.path.abspath(path)}")
# then call load_config(path)

try:
    config = load_config(config_path)
except TrainerConfigError as e:
    print(f"Fix config path: {e}")
    sys.exit(2)

When it happens

Trigger: Running `mlagents-learn path/to/config.yaml` where the file doesn't exist, the path is relative to a different working directory, or the file is unreadable (permissions). Called by main and from_argparse.

Common situations: Typos in --config path, running the CLI from a different cwd than expected, deleted/moved YAML after upgrading, or passing a directory instead of a file.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

• Couldn't launch the {file_name} environment. Provided filena
• There was an error decoding Config file from {config_path}.
• Error parsing yaml file. Please check for formatting errors.
• The demonstration file or directory {path} does not exist.
• Could not initialize from {init_file}. file does not exists

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