{"record":{"id":"77501c998b25effe","repo":"Unity-Technologies/ml-agents","slug":"couldn-t-launch-the-file-name-environment-provi","errorCode":null,"errorMessage":"Couldn't launch the {file_name} environment. Provided filename does not match any environments.","messagePattern":"Couldn't launch the (.+?) environment\\. Provided filename does not match any environments\\.","errorType":"exception","errorClass":"UnityEnvironmentException","httpStatus":null,"severity":"error","filePath":"ml-agents-envs/mlagents_envs/env_utils.py","lineNumber":101,"sourceCode":"                c\n                for c in glob.glob(os.path.join(cwd, env_path, \"*.exe\"))\n                if c not in crash_handlers\n            ]\n        if len(candidates) > 0:\n            launch_string = candidates[0]\n    return launch_string\n\n\ndef launch_executable(file_name: str, args: List[str]) -> subprocess.Popen:\n    \"\"\"\n    Launches a Unity executable and returns the process handle for it.\n    :param file_name: the name of the executable\n    :param args: List of string that will be passed as command line arguments\n    when launching the executable.\n    \"\"\"\n    launch_string = validate_environment_path(file_name)\n    if launch_string is None:\n        raise UnityEnvironmentException(\n            f\"Couldn't launch the {file_name} environment. Provided filename does not match any environments.\"\n        )\n    else:\n        logger.debug(f\"The launch string is {launch_string}\")\n        logger.debug(f\"Running with args {args}\")\n        # Launch Unity environment\n        subprocess_args = [launch_string] + args\n        # std_out_option = DEVNULL means the outputs will not be displayed on terminal.\n        # std_out_option = None is default behavior: the outputs are displayed on terminal.\n        std_out_option = subprocess.DEVNULL if logger.level > DEBUG else None\n        try:\n            return subprocess.Popen(\n                subprocess_args,\n                # start_new_session=True means that signals to the parent python process\n                # (e.g. SIGINT from keyboard interrupt) will not be sent to the new process on POSIX platforms.\n                # This is generally good since we want the environment to have a chance to shutdown,\n                # but may be undesirable in come cases; if so, we'll add a command-line toggle.\n                # Note that on Windows, the CTRL_C signal will still be sent.","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents-envs/mlagents_envs/env_utils.py#L83-L119","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nenv = UnityEnvironment(file_name=\"MyEnv\")  # not a resolvable executable\n# after\nenv = UnityEnvironment(file_name=\"/abs/path/builds/MyEnv.x86_64\")  # built Linux binary\nimport os; assert os.path.isfile(\"/abs/path/builds/MyEnv.x86_64\")","handlingStrategy":"validation","validationCode":"import os\nfrom mlagents_envs.env_utils import validate_environment_path\npath = validate_environment_path(file_name)\nif path is None:\n    raise FileNotFoundError(f\"No launchable Unity environment at {file_name!r}; build it first\")\nassert os.path.isfile(path)","typeGuard":null,"tryCatchPattern":"try:\n    env = UnityEnvironment(file_name=file_name)\nexcept UnityEnvironmentException as e:\n    print(f\"Build the Unity environment and pass the binary path: {e}\")\n    raise","preventionTips":["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"],"tags":["python","ml-agents","environment-launch","file-not-found","executable"],"backgroundTag":"executable-not-found","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}