HMCL-dev/HMCL · error · JsonParseException

ForgeVersionRoot mcversion cannot be null

Error message

ForgeVersionRoot mcversion cannot be null

What it means

ForgeVersionRoot.validate() throws this JsonParseException when the 'mcversion' field is null in the parsed Forge root metadata. The Minecraft version binds the Forge build to a game version and is required for HMCL to proceed with installation.

Solutions

1. Clear the cached Forge metadata and re-download from the remote repository.
2. Check the JSON contains a non-null 'mcversion' matching the target game version.
3. Switch mirrors or update HMCL.

Example fix

// before
ForgeVersionRoot root = JsonUtils.fromJson(json, ForgeVersionRoot.class);
root.validate();
// after
ForgeVersionRoot root = JsonUtils.fromJson(json, ForgeVersionRoot.class);
if (root == null || root.getMcversion() == null) {
    root = refetchForgeVersionRoot(mcVersion);
}
root.validate();

if (rootJson == null || !rootJson.has("mcversion")) refetchForgeRoot();

boolean hasMcVersion(ForgeVersionRoot r) { return r != null && r.getMcversion() != null; }

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

When it happens

Trigger: validate() on a ForgeVersionRoot deserialized from JSON missing 'mcversion' — incomplete feed entry, corrupted cache, or upstream schema change.

Common situations: Mirror served a partial record, JSON truncated in transit, or a cached entry written by an older HMCL/older metadata format.

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 number 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/617da478e200464c. Report an issue: GitHub.

Appendix: source

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

    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)