HMCL-dev/HMCL · error · IllegalStateException

Cannot install Terracotta

Error message

Cannot install Terracotta %s: system installer exited with code %d

What it means

Raised in MacOSProvider.install() when the macOS system 'installer' utility (invoked through osascript with administrator privileges) exits non-zero, meaning the Terracotta .pkg failed to install on the host system. This is a process-level failure: the package itself or the privileged installation step rejected or aborted, not a download or validation problem.

Solutions

  1. Check the ManagedProcess log output for the installer's exit reason (e.g. damaged package, insufficient disk space, permission denial on the osascript prompt).
  2. Re-download or re-export the Terracotta .pkg and retry the installation.
  3. Run 'sudo installer -pkg <pkg> -target /' manually in a terminal to see the installer's detailed error message.
Defensive patterns

Strategy: try-catch

When it happens

Trigger: Thrown at HMCL/src/main/java/org/jackhuang/hmcl/terracotta/provider/MacOSProvider.java:83 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

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

            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());
                } catch (IOException e) {
                    LOG.warning("Cannot remove temporary Terracotta package file.", e);
                }

                if (process.getExitCode() != 0) {
                    throw new IllegalStateException(String.format(
                            "Cannot install Terracotta %s: system installer exited with code %d", movedInstaller, process.getExitCode()
                    ));
                }
            });
        });
    }

    @Override
    public List<String> ofCommandLine(Path path) {
        return List.of(executable.toString(), "--hmcl", path.toString());
    }
}

View on GitHub (pinned to 24702dc5a0)