{"record":{"id":"2ad41d3abb6fbedf","repo":"HMCL-dev/HMCL","slug":"cannot-locate-osascript-system-executable-on-mac","errorCode":null,"errorMessage":"Cannot locate 'osascript' system executable on MacOS for installing Terracotta.","messagePattern":"Cannot locate 'osascript' system executable on MacOS for installing Terracotta\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"HMCL/src/main/java/org/jackhuang/hmcl/terracotta/provider/MacOSProvider.java","lineNumber":59,"sourceCode":"        this.executable = executable;\n        this.installer = installer;\n    }\n\n    @Override\n    public Status status() throws IOException {\n        if (!Files.exists(Path.of(\"/Applications/terracotta.app\"))) {\n            return Status.NOT_EXIST;\n        }\n\n        return bundle.status();\n    }\n\n    @Override\n    public Task<?> install(Path pkg) throws IOException {\n        return super.install(pkg).thenComposeAsync(() -> {\n            Path osascript = SystemUtils.which(\"osascript\");\n            if (osascript == null) {\n                throw new IllegalStateException(\"Cannot locate 'osascript' system executable on MacOS for installing Terracotta.\");\n            }\n\n            Path movedInstaller = Files.createTempDirectory(Metadata.HMCL_USER_HOME, \"terracotta-pkg\")\n                    .toRealPath()\n                    .resolve(FileUtils.getName(installer));\n            Files.copy(installer, movedInstaller, StandardCopyOption.REPLACE_EXISTING);\n\n            ManagedProcess process = new ManagedProcess(new ProcessBuilder(\n                    osascript.toString(), \"-e\", String.format(\n                    \"do shell script \\\"installer -pkg '%s' -target /\\\" with prompt \\\"%s\\\" with administrator privileges\",\n                    movedInstaller, i18n(\"terracotta.sudo_installing\")\n            )));\n            process.pumpInputStream(SystemUtils::onLogLine);\n            process.pumpErrorStream(SystemUtils::onLogLine);\n\n            return Task.fromCompletableFuture(process.getProcess().onExit()).thenRunAsync(() -> {\n                try {\n                    FileUtils.cleanDirectory(movedInstaller.getParent());","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCL/src/main/java/org/jackhuang/hmcl/terracotta/provider/MacOSProvider.java#L41-L77","documentation":"MacOSProvider.install first installs the terracotta package, then needs macOS's osascript to run the AppleScript steps; if SystemUtils.which('osascript') finds nothing on PATH it throws IllegalStateException because installation cannot continue without it.","triggerScenarios":"Running terracotta install on a macOS system where the osascript executable cannot be located — broken/minimal system install, stripped PATH in the launcher environment, or a corrupted macOS system.","commonSituations":"Launching HMCL from an environment with a nonstandard PATH (e.g. IDE or daemon with minimal env) hiding /usr/bin; macOS systems with damaged system binaries.","solutions":["Ensure osascript exists at /usr/bin/osascript and /usr/bin is on PATH when launching HMCL","Repair the macOS system (osascript is a standard system tool; absence indicates damage or SIP issues)","Launch HMCL from a normal shell/terminal environment with the default PATH","Catch IllegalStateException in the installer and report that macOS scripting support is unavailable"],"exampleFix":"// before\nenv PATH=/usr/local/bin hmcl\n// after\nenv PATH=/usr/bin:/bin:/usr/local/bin hmcl","handlingStrategy":"validation","validationCode":"if (SystemUtils.which(\"osascript\") == null) { throw new IllegalStateException(\"osascript required for terracotta install on macOS\"); }","typeGuard":null,"tryCatchPattern":"try { provider.install(pkg); } catch (IllegalStateException e) { UI.error(\"macOS 'osascript' tool not found; cannot install terracotta\"); }","preventionTips":["Run the installer from a normal user session with standard PATH","Verify /usr/bin/osascript exists before macOS-specific installs","Avoid mutating PATH for GUI-launched processes"],"tags":["macos","environment","dependency"],"backgroundTag":"missing-env-var","analyzedSha":"24702dc5a0214034f4c27166d5fd30cad08cec19","analyzedAt":"2026-09-10T12:36:46.680Z","contentChangedAt":"2026-09-10T12:36:46.680Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}