HMCL-dev/HMCL · error · JsonParseException

ForgeVersion version cannot be null

Error message

ForgeVersion version cannot be null

What it means

This is a generic validation guard in ForgeVersion.validate(): after JSON deserialization, the version field is null, meaning the remote Forge metadata entry is missing its required version identifier. As a sentinel check it fires on any incomplete server response rather than a specific malformed value.

Solutions

1. Supply the missing 'version' field in the JSON entry
2. Catch JsonParseException and filter out malformed entries
3. Refresh the version list from a reliable mirror

Example fix

// before
{"files": [...]} // version omitted
version.validate();
// after
{"version": "47.1.3", "mcversion": "1.20.1", "files": [...]}
version.validate();

if (versionObject.get("version") == null || versionObject.get("version").isJsonNull())
    throw new JsonParseException("ForgeVersion version missing");

static boolean hasVersion(JsonObject entry) {
    return entry.get("version") instanceof JsonPrimitive p && p.isString() && !p.getAsString().isBlank();
}

try {
    forgeVersion.validate();
} catch (JsonParseException e) {
    LOG.warning("Skipping entry with missing version: " + e.getMessage());
}

When it happens

Trigger: Parsing a Forge version list JSON entry that lacks a 'version' string and then calling validate().

Common situations: Mirror API returning partial entries, manual edits to cached version JSON, or mapping changes between BMCLAPI and the local model.

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
• Missing game manifest
• Game manifest inherits from another manifest
• "Invalid metadata file: " + jarInJarMetadata

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/download/forge/ForgeBMCLVersionList.java:195

            return modified;
        }

        @NotNull
        public String getVersion() {
            return version;
        }

        @NotNull
        public List<File> 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");
        }

        @Immutable
        public static final class File {
            private final String format;
            private final String category;
            private final String hash;

            public File() {
                this("", "", "");
            }

            public File(String format, String category, String hash) {
                this.format = format;
                this.category = category;
                this.hash = hash;

View on GitHub (pinned to 24702dc5a0)