Unity-Technologies/ml-agents · error · UnityTrainerException

Could not initialize from {init_file}. file does not exists

Error message

Could not initialize from {init_file}. file does not exists or is not a `.pt` file

What it means

UnityTrainerException thrown by _validate_init_full_path when the --init-file path passed to a trainer is either not an existing file or does not have a .pt extension. ML-Agents requires initialization from a previously saved PyTorch checkpoint, so the path must point to a real .pt model file. This is a startup-time configuration validation, raised before training begins.

Source

Thrown at ml-agents/mlagents/trainers/directory_utils.py:75

    for behavior_name, ts in behaviors.items():
        if ts.init_path is None:
            # set default if None
            ts.init_path = os.path.join(
                init_dir, behavior_name, DEFAULT_CHECKPOINT_NAME
            )
        elif not os.path.dirname(ts.init_path):
            # update to full path if just the file name
            ts.init_path = os.path.join(init_dir, behavior_name, ts.init_path)
        _validate_init_full_path(ts.init_path)


def _validate_init_full_path(init_file: str) -> None:
    """
    Validate initialization path to be a .pt file
    :param init_file: full path to initialization checkpoint file
    """
    if not (os.path.isfile(init_file) and init_file.endswith(".pt")):
        raise UnityTrainerException(
            f"Could not initialize from {init_file}. file does not exists or is not a `.pt` file"
        )

View on GitHub (pinned to 3ecb446f75)

Solutions

Verify the file exists: run ls on the exact path you passed to --init-file (or Path(init_file).exists() in Python).
Confirm the file has a .pt extension; if you only have .onnx/.pth, re-save the model with torch.save as .pt or retrain to produce a checkpoint.
If the path is relative, either cd to the expected directory or pass an absolute path (os.path.abspath).
Point --init-file at the correct run's checkpoint, e.g. results/<run_id>/<behavior_name>/<behavior_name>-<steps>.pt.

Example fix

// before
mlagents-learn config.yaml --init-file=results/run1/3DBall/3DBall-50000.onnx
// after
mlagents-learn config.yaml --init-file=results/run1/3DBall/3DBall-50000.pt

Defensive patterns

Strategy: validation

Validate before calling

import os
init_file = "results/run1/3DBall/3DBall-50000.pt"
if not (os.path.isfile(init_file) and init_file.endswith(".pt")):
    raise ValueError(f"--init-file must be an existing .pt file, got: {init_file}")

Type guard

def is_valid_checkpoint(path: str) -> bool:
    return isinstance(path, str) and path.endswith(".pt") and os.path.isfile(path)

Try / catch

from mlagents.trainers.exception import UnityTrainerException
try:
    trainer = setup_init_path(trainer, init_path)
except UnityTrainerException:
    logger.warning("Invalid init checkpoint, starting from scratch")
    init_path = None

Prevention

Always pass absolute paths to --init-file
Glob for results/<run>/**/*.pt before launching to confirm a checkpoint exists
Never point --init-file at .onnx/.pth/.ckpt artifacts

When it happens

Trigger: Calling setup_init_path with an init_file whose full path fails os.path.isfile() (file missing, typo, wrong working directory) or whose name does not end with '.pt' (e.g. a .ckpt, .pth, .onnx, or .nn file, or a directory path).

Common situations: Passing a TensorFlow-era .ckpt or an older .pth checkpoint to a newer mlagents-learn run; typos or relative paths resolved from the wrong CWD; pointing at a Model asset exported to .onnx instead of the trainer checkpoint .pt.

Related errors

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