{"record":{"id":"3bedb64f0a2884ee","repo":"HMCL-dev/HMCL","slug":"client-mappings-download-info-not-found","errorCode":null,"errorMessage":"client_mappings download info not found","messagePattern":"client_mappings download info not found","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"HMCLCore/src/main/java/org/jackhuang/hmcl/download/forge/ForgeNewInstallTask.java","lineNumber":371,"sourceCode":"        return options;\n    }\n\n    private Task<?> patchDownloadMojangMappingsTask(Processor processor, Map<String, String> vars) {\n        Map<String, String> options = parseOptions(processor.getArgs(), vars);\n        if (!\"DOWNLOAD_MOJMAPS\".equals(options.get(\"task\")) || !\"client\".equals(options.get(\"side\")))\n            return null;\n        String version = options.get(\"version\");\n        String output = options.get(\"output\");\n        if (version == null || output == null)\n            return null;\n\n        LOG.info(\"Patching DOWNLOAD_MOJMAPS task\");\n        return new GameInstanceJsonDownloadTask(version, dependencyManager)\n                .thenComposeAsync(json -> {\n                    DownloadInfo mappings = fromNonNullJson(json, GameInstanceManifest.class)\n                            .getDownloads().get(DownloadType.CLIENT_MAPPINGS);\n                    if (mappings == null) {\n                        throw new Exception(\"client_mappings download info not found\");\n                    }\n\n                    List<URI> mappingsUrl = dependencyManager.getDownloadProvider()\n                            .injectURLWithCandidates(mappings.getUrl());\n                    var mappingsTask = new FileDownloadTask(\n                            mappingsUrl,\n                            Path.of(output),\n                            FileDownloadTask.IntegrityCheck.of(\"SHA-1\", mappings.getSha1()));\n                    mappingsTask.setCaching(true);\n                    mappingsTask.setCacheRepository(dependencyManager.getCacheRepository());\n                    return mappingsTask;\n                });\n    }\n\n    private Task<?> createProcessorTask(Processor processor, Map<String, String> vars) {\n        Task<?> task = patchDownloadMojangMappingsTask(processor, vars);\n        if (task == null) {\n            task = new ProcessorTask(processor, vars);","sourceCodeStart":353,"sourceCodeEnd":389,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/download/forge/ForgeNewInstallTask.java#L353-L389","documentation":"When patching the DOWNLOAD_MOJMAPS processor, HMCL fetches the Minecraft version JSON and reads downloads.client_mappings. If that entry is missing (null), it throws Exception(\"client_mappings download info not found\"). This means the version manifest for the target Minecraft version does not publish client mapping download info, which Forge's processor would need.","triggerScenarios":"Installing Forge for a Minecraft version whose version JSON lacks a downloads.client_mappings entry — the DOWNLOAD_MOJMAPS processor exists in the Forge installer but the Mojang manifest for that version has no mapping URL.","commonSituations":"Very old Minecraft versions (pre-1.14.4) or snapshots where client_mappings is absent; mirror/CDN serving an outdated or partial version manifest; custom/proxied version JSON missing the downloads block.","solutions":["Check the version JSON at piston-meta.mojang.com for that version and confirm downloads.client_mappings exists","Force HMCL to refresh its version metadata cache and retry","Install a Forge build for a Minecraft version that publishes client mappings (1.14.4+)","Use a different download provider/mirror that serves complete Mojang manifests"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// check the version manifest publishes client_mappings before installing\nJsonObject v = fetchJson(\"https://piston-meta.mojang.com/mc/game/version_json_v2.json\");\n// for the target version's json:\nJsonObject downloads = versionJson.getAsJsonObject(\"downloads\");\nif (downloads == null || !downloads.has(\"client_mappings\"))\n    throw new IllegalStateException(\"client_mappings unavailable for this version\");","typeGuard":null,"tryCatchPattern":"try { installTask.execute(); } catch (Exception e) { if (\"client_mappings download info not found\".equals(e.getMessage())) { useForgeVersionForMappedMcVersion(); } else throw e; }","preventionTips":["Install Forge only for Minecraft versions >= 1.14.4 that publish client mappings","Refresh HMCL's version metadata cache if manifests may be stale","Use mirrors that serve complete Mojang version JSONs","Check the target version's JSON manually when installs fail early"],"tags":["java","forge-installer","mappings","manifest"],"backgroundTag":"resource-not-found","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"}