HMCL-dev/HMCL · error · JsonParseException

ForgeVersion files cannot be null

Error message

ForgeVersion files cannot be null

What it means

ForgeVersion.validate() throws this JsonParseException when the parsed Forge install-profile JSON has no 'files' array. HMCL requires the files list to decide which artifacts to download and install for the Forge version; without it the version record is unusable.

Solutions

1. Re-fetch the Forge version JSON from the remote repository (delete any local cached copy first).
2. Check network/proxy integrity — re-download and confirm the JSON contains a non-null 'files' array.
3. Update HMCL; the feed format may have changed for the Forge version in question.

Example fix

// before: trusting cached JSON
ForgeVersion v = JsonUtils.fromJson(json, ForgeVersion.class);
v.validate();
// after: guard before validate
ForgeVersion v = JsonUtils.fromJson(json, ForgeVersion.class);
if (v == null || v.getFiles() == null) {
    v = refetchForgeVersion(versionId); // re-download instead of failing
}
v.validate();

if (versionJson == null || !versionJson.has("files") || versionJson.get("files").isJsonNull()) refetch();

boolean hasFiles(ForgeVersion v) { return v != null && v.getFiles() != null; }

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

When it happens

Trigger: Calling validate() on a ForgeVersion deserialized from JSON whose 'files' field is absent or explicitly null — typically a truncated, partially written, or malformed remote Forge JSON feed entry.

Common situations: The BMCLAPI/Meta Forge version list returned an incomplete entry, a proxy or cache stripped fields, or the downloaded version JSON was corrupted in transit.

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 version 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/395e608d94dc5b80. Report an issue: GitHub.

Appendix: source

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

        return version;
    }

    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)