What causes "Malformed forge installer file" in HMCL-dev/HMCL?

Delete the cached installer and re-download it, then compare file size with the official listing

HMCL-dev/HMCL · error · ArtifactMalformedException

Malformed forge installer file

Error message

Malformed forge installer file

What it means

ForgeOldInstallTask.execute() wraps its whole install-profile processing in a try block; a java.util.zip.ZipException raised while reading entries from the legacy installer (e.g. extracting the universal forge jar or reading install_profile.json contents) is converted to ArtifactMalformedException("Malformed forge installer file"). The archive itself is unreadable at some point mid-processing.

Solutions

Delete the cached installer and re-download it, then compare file size with the official listing
Test archive integrity ('unzip -t installer.jar') to confirm corruption
Check free disk space and exclude the HMCL cache from antivirus scanning
Use a different mirror or network to rule out transfer corruption

Defensive patterns

Strategy: try-catch

Validate before calling

// test archive integrity before install
Process p = new ProcessBuilder("unzip", "-t", installer.toString()).start();
if (p.waitFor() != 0) throw new IllegalStateException("corrupt zip: " + installer);

Try / catch

try { installTask.execute(); } catch (ArtifactMalformedException e) { Files.deleteIfExists(installer); reDownloadFromOfficialMirror(); }

Prevention

Verify installer file size/SHA-1 against Forge maven metadata
Avoid interrupted downloads; retry on flaky networks
Exclude launcher cache directories from AV real-time scanning
Clear cache after any crashed or cancelled install

When it happens

Trigger: ZipFile read of the legacy forge installer throws ZipException during entry extraction/parsing inside execute() — truncated central directory, CRC failures, or partial file flushed to disk.

Common situations: Interrupted downloads leaving truncated jars; filesystem/disk errors; files corrupted in transit through proxies; cached installer damaged after an earlier crash.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/download/forge/ForgeOldInstallTask.java:95

            Library forgeLibrary = new Library(installProfile.install().getPath());
            GameRepository gameRepository = dependencyManager.getGameRepository();
            Path forgeFile = gameRepository.getLayout().getLibraryFile(manifest.id(), forgeLibrary);
            Files.createDirectories(forgeFile.getParent());

            ZipEntry forgeEntry = zipFile.getEntry(installProfile.install().getFilePath());
            try (InputStream is = zipFile.getInputStream(forgeEntry);
                 OutputStream os = Files.newOutputStream(forgeFile, StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING)) {
                is.transferTo(os);
            }

            setResult(GameInstancePatch.fromManifest(
                    installProfile.versionInfo(),
                    GameComponentType.FORGE.getPatchId(),
                    selfVersion,
                    GameInstancePatch.PRIORITY_LOADER));
            dependencies.add(dependencyManager.checkComponentCompletionAsync(installProfile.versionInfo(), true));
        } catch (ZipException ex) {
            throw new ArtifactMalformedException("Malformed forge installer file", ex);
        }
    }
}

View on GitHub (pinned to 24702dc5a0)