{"record":{"id":"5b2c21828011bb7e","repo":"Unity-Technologies/ml-agents","slug":"error-when-trying-to-launch-environment-make-sur","errorCode":null,"errorMessage":"Error when trying to launch environment - make sure permissions are set correctly. For example \"chmod -R 755 {launch_string}\"","messagePattern":"Error when trying to launch environment - make sure permissions are set correctly\\. For example \"chmod -R 755 (.+?)\"","errorType":"exception","errorClass":"UnityEnvironmentException","httpStatus":null,"severity":"error","filePath":"ml-agents-envs/mlagents_envs/env_utils.py","lineNumber":126,"sourceCode":"        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.\n                start_new_session=True,\n                stdout=std_out_option,\n                stderr=std_out_option,\n            )\n        except PermissionError as perm:\n            # This is likely due to missing read or execute permissions on file.\n            raise UnityEnvironmentException(\n                f\"Error when trying to launch environment - make sure \"\n                f\"permissions are set correctly. For example \"\n                f'\"chmod -R 755 {launch_string}\"'\n            ) from perm\n","sourceCodeStart":108,"sourceCodeEnd":131,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents-envs/mlagents_envs/env_utils.py#L108-L131","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run chmod -R 755 on the executable path passed to UnityEnvironment (e.g. chmod -R 755 <launch_string>).","Verify the file_name points to the actual executable inside the build folder (e.g. path/MyEnv.x86_64), not the folder itself.","Check ownership with ls -l and chown to the user running the training script if needed.","In Docker/CI, ensure the executable bit survives COPY/ADD or re-chmod in the image build."],"exampleFix":"// before (shell)\n./3DBall/UnityEnvironment.x86_64\n# PermissionError -> 'Error when trying to launch environment'\n\n// after (shell)\nchmod -R 755 3DBall/UnityEnvironment.x86_64\n./3DBall/UnityEnvironment.x86_64","handlingStrategy":"validation","validationCode":"import os\nexecutable = 'path/to/env/UnityEnvironment.x86_64'\nif not os.path.isfile(executable):\n    raise FileNotFoundError(f'{executable} does not exist')\nif not os.access(executable, os.X_OK | os.R_OK):\n    raise PermissionError(f'Run: chmod 755 {executable}')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always chmod 755 after extracting a Unity Linux build.","Verify the launch path points to the executable file, not its folder.","In Docker/CI, restore the executable bit after COPY (RUN chmod -R 755).","Check os.access(path, os.X_OK) before constructing UnityEnvironment."],"tags":["permissions","subprocess","environment-launch"],"backgroundTag":"permission-denied-executable","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}