HMCL-dev/HMCL · error · JsonParseException

NeoForgeVersion rawVersion cannot be null.

Error message

NeoForgeVersion rawVersion cannot be null.

What it means

NeoForgeBMCLVersionList's inner NeoForgeVersion model represents one NeoForge version entry from the BMCLAPI metadata. validate() rejects entries whose rawVersion (the server-reported version string) is null, throwing JsonParseException so a malformed metadata record never becomes a usable RemoteVersion.

Solutions

1. Refresh the NeoForge version list (clear mirror cache) to re-fetch complete metadata.
2. Switch to a different metadata source/mirror (or the official maven) in download settings.
3. Retry later if the mirror is mid-sync for a new NeoForge release.
4. Update HMCL if the BMCLAPI schema changed and needs newer parsing code.

Example fix

// Not caller-fixable; guard at usage:
try {
    versionList.loadVersions(mcVersion);
} catch (JsonParseException e) {
    LOG.warning("Malformed NeoForge metadata from mirror", e); // retry or switch mirror
}

// Inspect mirror metadata before loading versions
if (metadataJson == null || !metadataJson.has("versions")) { switchMirror(); }

if (version.getRawVersion() == null) { skipEntry(); }

try { list = versionList.loadVersions(mcVersion); }
catch (JsonParseException e) { LOG.warning("Malformed NeoForge metadata", e); list = versionList.loadVersionsFromOfficial(mcVersion); }

When it happens

Trigger: Deserializing a BMCLAPI NeoForge metadata JSON entry that is missing the raw version field, then calling validate() while loading the NeoForge version list for a given Minecraft version.

Common situations: BMCLAPI/mirror returning incomplete or schema-drifted metadata; a truncated API response; a newly published entry that hasn't been fully populated on the mirror yet.

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

• NeoForgeVersion mcversion cannot be null.
• NeoForgeVersion version cannot be null.
• GameRemoteVersion id cannot be blank
• GameRemoteVersion url cannot be blank
• accountID is missing

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/download/neoforge/NeoForgeBMCLVersionList.java:100

    @Immutable
    private static final class NeoForgeVersion implements Validation {
        private final String rawVersion;

        private final String version;

        @SerializedName("mcversion")
        private final String mcVersion;

        public NeoForgeVersion(String rawVersion, String version, String mcVersion) {
            this.rawVersion = rawVersion;
            this.version = version;
            this.mcVersion = mcVersion;
        }

        @Override
        public void validate() throws JsonParseException {
            if (this.rawVersion == null) {
                throw new JsonParseException("NeoForgeVersion rawVersion cannot be null.");
            }
            if (this.version == null) {
                throw new JsonParseException("NeoForgeVersion version cannot be null.");
            }
            if (this.mcVersion == null) {
                throw new JsonParseException("NeoForgeVersion mcversion cannot be null.");
            }
        }
    }
}

View on GitHub (pinned to 24702dc5a0)