{"record":{"id":"94e756042f86af9a","repo":"HMCL-dev/HMCL","slug":"malformed-forge-installer-file","errorCode":null,"errorMessage":"Malformed forge installer file","messagePattern":"Malformed forge installer file","errorType":"validation","errorClass":"ArtifactMalformedException","httpStatus":null,"severity":"error","filePath":"HMCLCore/src/main/java/org/jackhuang/hmcl/download/forge/ForgeNewInstallTask.java","lineNumber":326,"sourceCode":"            forgeVersion = JsonUtils.fromNonNullJson(Files.readString(fs.getPath(profile.getJson())), GameInstanceManifest.class);\n\n            for (Library library : profile.getLibraries()) {\n                Path file = fs.getPath(\"maven\").resolve(library.getPath());\n                if (Files.exists(file)) {\n                    Path dest = gameRepository.getLayout().getLibraryFile(manifest.id(), library);\n                    FileUtils.copyFile(file, dest);\n                }\n            }\n\n            if (profile.getPath().isPresent()) {\n                Path mainJar = profile.getPath().get().getPath(fs.getPath(\"maven\"));\n                if (Files.exists(mainJar)) {\n                    Path dest = gameRepository.getLayout().getArtifactFile(profile.getPath().get());\n                    FileUtils.copyFile(mainJar, dest);\n                }\n            }\n        } catch (ZipException ex) {\n            throw new ArtifactMalformedException(\"Malformed forge installer file\", ex);\n        }\n\n        dependents.add(new GameLibrariesTask(dependencyManager, manifest, true, profile.getLibraries()));\n    }\n\n    private Map<String, String> parseOptions(List<String> args, Map<String, String> vars) {\n        Map<String, String> options = new LinkedHashMap<>();\n        String optionName = null;\n        for (String arg : args) {\n            if (arg.startsWith(\"--\")) {\n                if (optionName != null) {\n                    options.put(optionName, \"\");\n                }\n                optionName = arg.substring(2);\n            } else {\n                if (optionName == null) {\n                    // ignore\n                } else {","sourceCodeStart":308,"sourceCodeEnd":344,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/download/forge/ForgeNewInstallTask.java#L308-L344","documentation":"During preExecute, ForgeNewInstallTask opens the downloaded Forge installer jar as a read-only zip filesystem. If the file is not a valid zip archive (java.util.zip.ZipException), it wraps the failure in ArtifactMalformedException(\"Malformed forge installer file\"). The installer download is corrupt, incomplete, or not a jar at all (e.g. an HTML error page).","triggerScenarios":"installer Path passed to ForgeNewInstallTask points to a file that CompressingUtils.createReadOnlyZipFileSystem cannot open as zip — corrupt download, truncated file, HTML/blocked response saved as .jar, or wrong file passed as installer.","commonSituations":"Unstable network/mirror corrupting the download; download servers returning error pages; proxy/antivirus truncating files; user manually placing a wrong file in the cache; disk full during download.","solutions":["Delete the cached Forge installer file and re-download (clear HMCL download cache)","Check disk space and network/proxy stability, then retry installation","Verify the file is a real jar: 'file installer.jar' or try opening it with a zip tool","Switch download source/mirror in HMCL settings and retry"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// pre-validate the installer is a zip before invoking the task\ntry (var zin = new java.util.zip.ZipInputStream(Files.newInputStream(installer))) {\n    if (zin.getNextEntry() == null) throw new IllegalStateException(\"not a zip/jar: \" + installer);\n}","typeGuard":null,"tryCatchPattern":"try { installTask.execute(); } catch (ArtifactMalformedException e) { Files.deleteIfExists(installer); reDownloadForgeInstaller(); }","preventionTips":["Re-download installer if its size or SHA-1 differs from maven metadata","Ensure stable network/disk during download","Exclude the HMCL cache from antivirus tampering","Verify the artifact is the '-installer.jar', not a universal jar"],"tags":["java","zip","corrupt-file","forge-installer"],"backgroundTag":"checksum-mismatch","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"}