HMCL-dev/HMCL · error · JsonParseException

ForgeVersion version cannot be null

Error message

ForgeVersion version cannot be null

What it means

ForgeVersion.validate() throws this JsonParseException when the 'version' field of the Forge install-profile JSON is null. HMCL needs the Forge version identifier to name and resolve the installed profile; a record without it is invalid.

Solutions

1. Delete the cached Forge version JSON and re-download from the remote repository.
2. Verify the JSON actually contains a 'version' string matching the requested Forge build.
3. Update HMCL or switch the download mirror (e.g. BMCLAPI vs official Forge meta).

Example fix

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

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

boolean hasVersion(ForgeVersion v) { return v != null && v.getVersion() != null; }

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

When it happens

Trigger: validate() is invoked on a ForgeVersion whose JSON lacked the 'version' field, e.g. an unexpected upstream schema or a hand-edited/corrupted local file.

Common situations: Upstream Forge metadata format changed, a mirror returned an incomplete entry, or a locally cached JSON was edited/truncated.

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 mcversion 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/d9432dc1ddf41288. Report an issue: GitHub.

Appendix: source

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

    public int getBuild() {
        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)