HMCL-dev/HMCL · error · JsonParseException

ForgeVersionRoot number cannot be null

Error message

ForgeVersionRoot number cannot be null

What it means

ForgeVersionRoot.validate() throws this JsonParseException when the 'number' field (the Forge build number) is null in the parsed promoter/root JSON. HMCL needs the build number to resolve the concrete Forge installer; the record is unusable without it.

Solutions

1. Verify Forge actually publishes a build for the requested Minecraft version before resolving.
2. Re-fetch the Forge version list JSON from the official source or a different mirror.
3. Update HMCL to handle the current Forge metadata format.

Example fix

// before
ForgeVersionRoot root = JsonUtils.fromJson(json, ForgeVersionRoot.class);
root.validate();
// after
ForgeVersionRoot root = JsonUtils.fromJson(json, ForgeVersionRoot.class);
if (root == null || root.getNumber() == null) {
    throw new UnsupportedGameVersionException(mcVersion); // no Forge build exists
}
root.validate();

if (rootJson == null || !rootJson.has("number")) throw new IllegalStateException("No Forge build for " + mcVersion);

boolean hasNumber(ForgeVersionRoot r) { return r != null && r.getNumber() != null; }

try { root.validate(); } catch (JsonParseException e) { fallbackToOtherMirror(); }

When it happens

Trigger: validate() on a ForgeVersionRoot whose source JSON (e.g. https://files.minecraftforge.net promos/versions list) lacked 'number', typically because the lookup for that Minecraft version returned an unexpected structure.

Common situations: Requesting a Minecraft version Forge has not published a build for, a mirror returning empty/placeholder entries, or the promoter list format changing.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• ForgeVersion files cannot be null
• ForgeVersion version cannot be null
• ForgeVersion mcversion cannot be null
• ForgeVersionRoot mcversion cannot be null
• authlib-injectors.json -> urls cannot be null.

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/download/forge/ForgeVersionRoot.java:102

        return branches;
    }

    public Map<String, int[]> getGameVersions() {
        return mcversion;
    }

    public Map<String, Integer> getPromos() {
        return promos;
    }

    public Map<Integer, ForgeVersion> getNumber() {
        return number;
    }

    @Override
    public void validate() throws JsonParseException {
        if (number == null)
            throw new JsonParseException("ForgeVersionRoot number cannot be null");
        if (mcversion == null)
            throw new JsonParseException("ForgeVersionRoot mcversion cannot be null");
    }

}

View on GitHub (pinned to 24702dc5a0)