HMCL-dev/HMCL · error · IOException

Game processor exited abnormally with code

Error message

Game processor exited abnormally with code ${exitCode}

What it means

Thrown as IOException when the external NeoForge/Forge install processor (a Java main class spawned via SystemUtils.callExternalProcess) exits with a non-zero exit code. The processor itself failed — HMCL only reports the exit code; the real cause is in the processor's captured stdout/stderr.

Solutions

Read the processor's stdout/stderr in the HMCL log to find the processor's own error
Switch the default Java runtime (try a Java 8 or the recommended version for that loader)
Verify/re-download the Minecraft client jar and installer
Free disk space and ensure the game directory is writable and not blocked by antivirus
Retry the installation from scratch in a clean directory

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-checks: valid client jar, adequate disk space, correct Java runtime
if (!Files.isRegularFile(minecraftJar)) throw new IllegalStateException("client jar missing");
Files.getUsableSpace(repoDir);

Try / catch

try { task.run(); } catch (IOException e) { if (e.getMessage().startsWith("Game processor exited abnormally")) { int code = parseExitCode(e.getMessage()); inspectProcessorLogAndRetry(code); } else throw e; }

Prevention

Select the correct Java runtime for the loader version
Keep the vanilla client jar intact and unmodified
Ensure free disk space and a writable game directory
Allow java.exe through antivirus/firewall

When it happens

Trigger: SystemUtils.callExternalProcess(command) returns exitCode != 0 after running `java -cp ... <mainClass> <parsed args>` for a processor, e.g. because the vanilla jar is invalid, mapped data is missing, disk is full, or the default Java runtime is broken.

Common situations: Corrupted Minecraft client jar; wrong/incompatible default Java version selected; out-of-memory or full disk during processing; antivirus blocking the spawned java process; installer version mismatched with the game version.

Related errors

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/download/neoforge/NeoForgeOldInstallTask.java:153

            classpath.add(jar.toString());
            command.add(String.join(File.pathSeparator, classpath));

            command.add(mainClass);

            List<String> args = new ArrayList<>(processor.getArgs().size());
            for (String arg : processor.getArgs()) {
                String parsed = parseLiteral(arg, vars);
                if (parsed == null)
                    throw new ArtifactMalformedException("Invalid forge installation configuration");
                args.add(parsed);
            }

            command.addAll(args);

            LOG.info("Executing external processor " + processor.getJar().toString() + ", command line: " + new CommandBuilder().addAll(command).toString());
            int exitCode = SystemUtils.callExternalProcess(command);
            if (exitCode != 0)
                throw new IOException("Game processor exited abnormally with code " + exitCode);

            for (Map.Entry<String, String> entry : outputs.entrySet()) {
                Path artifact = Paths.get(entry.getKey());
                if (!Files.isRegularFile(artifact))
                    throw new FileNotFoundException("File missing: " + artifact);

                String code;
                try (InputStream stream = Files.newInputStream(artifact)) {
                    code = DigestUtils.digestToString("SHA-1", stream);
                }

                if (!Objects.equals(code, entry.getValue())) {
                    Files.delete(artifact);
                    throw new ChecksumMismatchException("SHA-1", entry.getValue(), code);
                }
            }
        }
    }

View on GitHub (pinned to 24702dc5a0)