Unity-Technologies/ml-agents · error · UnityEnvironmentException

Error when trying to launch environment - make sure permissi

Error message

Error when trying to launch environment - make sure permissions are set correctly. For example "chmod -R 755 {launch_string}"

What it means

UnityEnvironmentException raised by env_utils.launch_executable when subprocess.Popen raises PermissionError while starting the Unity environment executable. The library could not read/execute the binary, usually because the build was not made executable after extraction or is owned by another user. The message suggests chmod -R 755 on the launch string.

Source

Thrown at ml-agents-envs/mlagents_envs/env_utils.py:126

        subprocess_args = [launch_string] + args
        # std_out_option = DEVNULL means the outputs will not be displayed on terminal.
        # std_out_option = None is default behavior: the outputs are displayed on terminal.
        std_out_option = subprocess.DEVNULL if logger.level > DEBUG else None
        try:
            return subprocess.Popen(
                subprocess_args,
                # start_new_session=True means that signals to the parent python process
                # (e.g. SIGINT from keyboard interrupt) will not be sent to the new process on POSIX platforms.
                # This is generally good since we want the environment to have a chance to shutdown,
                # but may be undesirable in come cases; if so, we'll add a command-line toggle.
                # Note that on Windows, the CTRL_C signal will still be sent.
                start_new_session=True,
                stdout=std_out_option,
                stderr=std_out_option,
            )
        except PermissionError as perm:
            # This is likely due to missing read or execute permissions on file.
            raise UnityEnvironmentException(
                f"Error when trying to launch environment - make sure "
                f"permissions are set correctly. For example "
                f'"chmod -R 755 {launch_string}"'
            ) from perm

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Run chmod -R 755 on the executable path passed to UnityEnvironment (e.g. chmod -R 755 <launch_string>).
2. Verify the file_name points to the actual executable inside the build folder (e.g. path/MyEnv.x86_64), not the folder itself.
3. Check ownership with ls -l and chown to the user running the training script if needed.
4. In Docker/CI, ensure the executable bit survives COPY/ADD or re-chmod in the image build.

Example fix

// before (shell)
./3DBall/UnityEnvironment.x86_64
# PermissionError -> 'Error when trying to launch environment'

// after (shell)
chmod -R 755 3DBall/UnityEnvironment.x86_64
./3DBall/UnityEnvironment.x86_64

import os
executable = 'path/to/env/UnityEnvironment.x86_64'
if not os.path.isfile(executable):
    raise FileNotFoundError(f'{executable} does not exist')
if not os.access(executable, os.X_OK | os.R_OK):
    raise PermissionError(f'Run: chmod 755 {executable}')

When it happens

Trigger: Calling UnityEnvironment(file_name='<path-to-unity-build>') where the executable file (or a needed file under it) lacks read or execute permission for the current user; Popen(launch_string, start_new_session=True, ...) in launch_executable catches PermissionError and re-raises this exception.

Common situations: Downloading/extracting a Unity Linux build from a zip or tarball that lost the executable bit; copying builds between machines or Docker layers; running as a non-root user in CI against root-owned files; Windows-built binaries copied to Linux without chmod.

Related errors

• Couldn't launch the {file_name} environment. Provided filena
• The folder {output_path} containing the generated model coul

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