HMCL-dev/HMCL · error · JsonParseException

ForgeVersion mcversion cannot be null

Error message

ForgeVersion mcversion cannot be null

What it means

ForgeVersion.validate() throws this JsonParseException when the 'mcversion' field (the target Minecraft version) is null. HMCL uses mcversion to match the Forge installer to a Minecraft version, so the field is mandatory.

Solutions

1. Re-download the Forge version JSON; clear any HMCL cache for that Forge entry.
2. Confirm the JSON's 'mcversion' matches the Minecraft version you are installing Forge for.
3. Try a different download source/mirror or update HMCL.

Example fix

// before
ForgeVersion v = JsonUtils.fromJson(json, ForgeVersion.class);
v.validate();
// after
ForgeVersion v = JsonUtils.fromJson(json, ForgeVersion.class);
if (v == null || v.getMcversion() == null) {
    v = refetchForgeVersion(versionId);
}
v.validate();

if (versionJson == null || !versionJson.has("mcversion")) refetch();

boolean hasMcVersion(ForgeVersion v) { return v != null && v.getMcversion() != null; }

try { v.validate(); } catch (JsonParseException e) { refetchForgeVersion(); }

When it happens

Trigger: validate() on a ForgeVersion deserialized from JSON missing 'mcversion' — malformed feed entry, corrupted cache, or schema drift in the Forge metadata source.

Common situations: Third-party mirror returned stripped metadata, download interrupted mid-write, or an old cached feed no longer matches the current parser expectations.

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
• ForgeVersionRoot number 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/368c7dfe30f55e38. Report an issue: GitHub.

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/download/forge/ForgeVersion.java:92

        return build;
    }

    public long getModified() {
        return modified;
    }

    public String[][] getFiles() {
        return files;
    }

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

}

View on GitHub (pinned to 24702dc5a0)