HMCL-dev/HMCL · error · Exception

client_mappings download info not found

Error message

client_mappings download info not found

What it means

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.

Solutions

1. Check the version JSON at piston-meta.mojang.com for that version and confirm downloads.client_mappings exists
2. Force HMCL to refresh its version metadata cache and retry
3. Install a Forge build for a Minecraft version that publishes client mappings (1.14.4+)
4. Use a different download provider/mirror that serves complete Mojang manifests

// check the version manifest publishes client_mappings before installing
JsonObject v = fetchJson("https://piston-meta.mojang.com/mc/game/version_json_v2.json");
// for the target version's json:
JsonObject downloads = versionJson.getAsJsonObject("downloads");
if (downloads == null || !downloads.has("client_mappings"))
    throw new IllegalStateException("client_mappings unavailable for this version");

try { installTask.execute(); } catch (Exception e) { if ("client_mappings download info not found".equals(e.getMessage())) { useForgeVersionForMappedMcVersion(); } else throw e; }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Illegal pattern (Bad escape):
• Illegal pattern (Unclosed ):
• Illegal pattern: Missing Key:
• Malformed forge installer file
• Minecraft client JAR not found:

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/download/forge/ForgeNewInstallTask.java:371

        return options;
    }

    private Task<?> patchDownloadMojangMappingsTask(Processor processor, Map<String, String> vars) {
        Map<String, String> options = parseOptions(processor.getArgs(), vars);
        if (!"DOWNLOAD_MOJMAPS".equals(options.get("task")) || !"client".equals(options.get("side")))
            return null;
        String version = options.get("version");
        String output = options.get("output");
        if (version == null || output == null)
            return null;

        LOG.info("Patching DOWNLOAD_MOJMAPS task");
        return new GameInstanceJsonDownloadTask(version, dependencyManager)
                .thenComposeAsync(json -> {
                    DownloadInfo mappings = fromNonNullJson(json, GameInstanceManifest.class)
                            .getDownloads().get(DownloadType.CLIENT_MAPPINGS);
                    if (mappings == null) {
                        throw new Exception("client_mappings download info not found");
                    }

                    List<URI> mappingsUrl = dependencyManager.getDownloadProvider()
                            .injectURLWithCandidates(mappings.getUrl());
                    var mappingsTask = new FileDownloadTask(
                            mappingsUrl,
                            Path.of(output),
                            FileDownloadTask.IntegrityCheck.of("SHA-1", mappings.getSha1()));
                    mappingsTask.setCaching(true);
                    mappingsTask.setCacheRepository(dependencyManager.getCacheRepository());
                    return mappingsTask;
                });
    }

    private Task<?> createProcessorTask(Processor processor, Map<String, String> vars) {
        Task<?> task = patchDownloadMojangMappingsTask(processor, vars);
        if (task == null) {
            task = new ProcessorTask(processor, vars);

View on GitHub (pinned to 24702dc5a0)