Unity-Technologies/ml-agents · error · UnityEnvironmentException

Couldn't launch the {file_name} environment. Provided filena

Error message

Couldn't launch the {file_name} environment. Provided filename does not match any environments.

What it means

launch_executable resolves file_name through validate_environment_path to an actual launchable Unity executable path; when no match is found (launch_string is None) it raises UnityEnvironmentException stating the provided filename doesn't match any environments. It means the executable could not be located on disk for the current platform.

Source

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

                c
                for c in glob.glob(os.path.join(cwd, env_path, "*.exe"))
                if c not in crash_handlers
            ]
        if len(candidates) > 0:
            launch_string = candidates[0]
    return launch_string


def launch_executable(file_name: str, args: List[str]) -> subprocess.Popen:
    """
    Launches a Unity executable and returns the process handle for it.
    :param file_name: the name of the executable
    :param args: List of string that will be passed as command line arguments
    when launching the executable.
    """
    launch_string = validate_environment_path(file_name)
    if launch_string is None:
        raise UnityEnvironmentException(
            f"Couldn't launch the {file_name} environment. Provided filename does not match any environments."
        )
    else:
        logger.debug(f"The launch string is {launch_string}")
        logger.debug(f"Running with args {args}")
        # Launch Unity environment
        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.

View on GitHub (pinned to 3ecb446f75)

Solutions

Build the environment first (Unity Editor: File > Build Settings > Build) and pass the built executable path.
Pass an absolute path to the built binary and confirm it exists and is executable (ls -l / chmod +x on Linux).
Use the platform-correct artifact: Linux binary (no extension), Windows .exe, macOS app executable inside the .app bundle.
Call mlagents_envs.env_utils.validate_environment_path(file_name) yourself to see what path it resolves to before launching.

Example fix

# before
env = UnityEnvironment(file_name="MyEnv")  # not a resolvable executable
# after
env = UnityEnvironment(file_name="/abs/path/builds/MyEnv.x86_64")  # built Linux binary
import os; assert os.path.isfile("/abs/path/builds/MyEnv.x86_64")

Defensive patterns

Strategy: validation

Validate before calling

import os
from mlagents_envs.env_utils import validate_environment_path
path = validate_environment_path(file_name)
if path is None:
    raise FileNotFoundError(f"No launchable Unity environment at {file_name!r}; build it first")
assert os.path.isfile(path)

Try / catch

try:
    env = UnityEnvironment(file_name=file_name)
except UnityEnvironmentException as e:
    print(f"Build the Unity environment and pass the binary path: {e}")
    raise

Prevention

Build the Unity project before training and pass the absolute binary path
chmod +x the Linux binary; use the OS-correct artifact (.exe / app / x86_64)
Run validate_environment_path first to confirm resolution
Avoid passing project folders or package files instead of built executables

When it happens

Trigger: Calling UnityEnvironment(file_name=...) / launch_executable with a path that doesn't exist, a directory, a non-executable file, a Linux binary built for another architecture, or a filename lacking the expected extension for the OS.

Common situations: Forgetting to build the Unity environment before training; relative path resolved from the wrong working directory; passing the .unitypackage or project folder instead of the built binary; on Linux running the macOS .app bundle; filename typo.

Related errors

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