Unity-Technologies/ml-agents · error · UnityEnvironmentException

The folder {output_path} containing the generated model coul

Error message

The folder {output_path} containing the generated model could not be accessed. Please make sure the permissions are set correctly.

What it means

TrainerController._create_output_path wraps os.makedirs in a try/except and re-raises UnityEnvironmentException when the model output folder cannot be created or accessed (permissions, invalid path, or a file existing at that path). Training cannot save models without a writable results directory, so it aborts early in start_learning.

Source

Thrown at ml-agents/mlagents/trainers/trainer_controller.py:89

    @timed
    def _save_models(self):
        """
        Saves current model to checkpoint folder.
        """
        if self.rank is not None and self.rank != 0:
            return

        for brain_name in self.trainers.keys():
            self.trainers[brain_name].save_model()
        self.logger.debug("Saved Model")

    @staticmethod
    def _create_output_path(output_path):
        try:
            if not os.path.exists(output_path):
                os.makedirs(output_path)
        except Exception:
            raise UnityEnvironmentException(
                f"The folder {output_path} containing the "
                "generated model could not be "
                "accessed. Please make sure the "
                "permissions are set correctly."
            )

    @timed
    def _reset_env(self, env_manager: EnvManager) -> None:
        """Resets the environment.

        Returns:
            A Data structure corresponding to the initial reset state of the
            environment.
        """
        new_config = self.param_manager.get_current_samplers()
        env_manager.reset(config=new_config)
        # Register any new behavior ids that were generated on the reset.
        self._register_new_behaviors(env_manager, env_manager.first_step_infos)

View on GitHub (pinned to 3ecb446f75)

Solutions

Choose a writable --results-dir, e.g. ./results or an absolute path under your home directory
Check/fix permissions with chmod/chown on the target directory
Ensure the output path is a directory, not an existing file
Create the parent directory manually and verify with a test write before launching training

Example fix

// before
mlagents-learn config.yaml --results-dir=/root/locked/results
// after
mlagents-learn config.yaml --results-dir=./results

Defensive patterns

Strategy: validation

Validate before calling

import os
output_path = "./results"
if os.path.exists(output_path) and not os.path.isdir(output_path):
    raise NotADirectoryError(output_path)
os.makedirs(output_path, exist_ok=True)
assert os.access(output_path, os.W_OK), f"{output_path} is not writable"

Type guard

def is_writable_dir(path) -> bool:
    try:
        os.makedirs(path, exist_ok=True)
        return os.path.isdir(path) and os.access(path, os.W_OK)
    except OSError:
        return False

Try / catch

from mlagents_envs.exception import UnityEnvironmentException
try:
    trainer_controller.start_learning()
except UnityEnvironmentException as e:
    logger.error(f"Output path problem: {e}")
    raise SystemExit("Use a writable --results-dir")

Prevention

Pass an explicit writable --results-dir relative to your project
Pre-create and chmod the results directory before long training runs
Avoid output paths on read-only mounts, network shares, or root-owned directories

When it happens

Trigger: Running mlagents-learn with --results-dir or run_options.output_path pointing to a read-only directory, a nonexistent parent on a non-writable mount, a path that exists as a file, or a disk where os.makedirs throws (PermissionError/ OSError).

Common situations: Docker containers writing to a read-only volume; output path under / or another root-owned directory; results dir inside a OneDrive/synced folder locked by the OS; typo producing an invalid path.

Related errors

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