{"record":{"id":"40a1d8d8b94a88c3","repo":"HMCL-dev/HMCL","slug":"malformed-forge-installer-file-40a1d8","errorCode":null,"errorMessage":"Malformed forge installer file","messagePattern":"Malformed forge installer file","errorType":"exception","errorClass":"ArtifactMalformedException","httpStatus":null,"severity":"error","filePath":"HMCLCore/src/main/java/org/jackhuang/hmcl/download/neoforge/NeoForgeOldInstallTask.java","lineNumber":310,"sourceCode":"            neoForgeVersion = 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":292,"sourceCodeEnd":328,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/download/neoforge/NeoForgeOldInstallTask.java#L292-L328","documentation":"Thrown when the NeoForge/Forge installer file cannot be read as a valid ZIP archive during preExecute. HMCL copies the installer's main JAR out of the downloaded archive via a zip filesystem, and a ZipException bubbling up means the installer download is corrupt or not a real zip.","triggerScenarios":"Downloading a Forge/NeoForge installer whose bytes are a truncated transfer, an HTML error page saved as a .jar, or a corrupted cache entry; then FileUtils.copyFile(mainJar, dest) inside the opened zip filesystem throws ZipException.","commonSituations":"Unstable mirror/BMCLAPI candidates returning partial files, disk full during download, proxy intercepting the download, or reusing a stale cached installer after an interrupted download.","solutions":["Delete the corrupted installer/cache and re-download the installer (verify file size/checksum if available).","Switch or retry the download provider/mirror candidates.","Check free disk space and that the download URL is not behind an error page (open the URL in a browser)."],"exampleFix":"// before\ncatch (ZipException ex) {\n    throw new ArtifactMalformedException(\"Malformed forge installer file\", ex);\n}\n// after\n// verify the downloaded installer before installing\nif (!CompressingUtils.checkZip(installerPath)) {\n    Files.deleteIfExists(installerPath); // force a fresh download\n    throw new ArtifactMalformedException(\"Malformed forge installer file\", null);\n}","handlingStrategy":"validation","validationCode":"if (!Files.exists(installerPath) || Files.size(installerPath) < 1024 || !CompressingUtils.checkZip(installerPath)) {\n    Files.deleteIfExists(installerPath); // force re-download\n    throw new IOException(\"Installer is not a valid zip: \" + installerPath);\n}","typeGuard":null,"tryCatchPattern":"try {\n    await(task);\n} catch (ArtifactMalformedException e) {\n    // delete cached installer and retry once\n    Files.deleteIfExists(installerPath);\n    await(task);\n}","preventionTips":["Validate the installer is a readable zip before installing","Prefer official download candidates/mirrors with checksum verification","Keep enough free disk space for downloads"],"tags":["zip","download","corrupt-file","neoforge","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"}