HMCL-dev/HMCL · error · IllegalStateException

Cannot locate 'osascript' system executable on MacOS for…

Error message

Cannot locate 'osascript' system executable on MacOS for installing Terracotta.

What it means

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.

Solutions

1. Ensure osascript exists at /usr/bin/osascript and /usr/bin is on PATH when launching HMCL
2. Repair the macOS system (osascript is a standard system tool; absence indicates damage or SIP issues)
3. Launch HMCL from a normal shell/terminal environment with the default PATH
4. Catch IllegalStateException in the installer and report that macOS scripting support is unavailable

Example fix

// before
env PATH=/usr/local/bin hmcl
// after
env PATH=/usr/bin:/bin:/usr/local/bin hmcl

if (SystemUtils.which("osascript") == null) { throw new IllegalStateException("osascript required for terracotta install on macOS"); }

try { provider.install(pkg); } catch (IllegalStateException e) { UI.error("macOS 'osascript' tool not found; cannot install terracotta"); }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Failed to find current HMCL location
• Unsupported platform: operating system
• The extension of is not 'sh', 'bash', 'ps1' or 'command'…
• Module jdk.zipfs does not exist

AI-assisted analysis of HMCL-dev/HMCL@24702dc5a0 (2026-09-10). Data as JSON: /api/errors/2ad41d3abb6fbedf. Report an issue: GitHub.

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/terracotta/provider/MacOSProvider.java:59

        this.executable = executable;
        this.installer = installer;
    }

    @Override
    public Status status() throws IOException {
        if (!Files.exists(Path.of("/Applications/terracotta.app"))) {
            return Status.NOT_EXIST;
        }

        return bundle.status();
    }

    @Override
    public Task<?> install(Path pkg) throws IOException {
        return super.install(pkg).thenComposeAsync(() -> {
            Path osascript = SystemUtils.which("osascript");
            if (osascript == null) {
                throw new IllegalStateException("Cannot locate 'osascript' system executable on MacOS for installing Terracotta.");
            }

            Path movedInstaller = Files.createTempDirectory(Metadata.HMCL_USER_HOME, "terracotta-pkg")
                    .toRealPath()
                    .resolve(FileUtils.getName(installer));
            Files.copy(installer, movedInstaller, StandardCopyOption.REPLACE_EXISTING);

            ManagedProcess process = new ManagedProcess(new ProcessBuilder(
                    osascript.toString(), "-e", String.format(
                    "do shell script \"installer -pkg '%s' -target /\" with prompt \"%s\" with administrator privileges",
                    movedInstaller, i18n("terracotta.sudo_installing")
            )));
            process.pumpInputStream(SystemUtils::onLogLine);
            process.pumpErrorStream(SystemUtils::onLogLine);

            return Task.fromCompletableFuture(process.getProcess().onExit()).thenRunAsync(() -> {
                try {
                    FileUtils.cleanDirectory(movedInstaller.getParent());

View on GitHub (pinned to 24702dc5a0)