HMCL-dev/HMCL · error · JsonParseException

NeoForgeVersion mcversion cannot be null.

Error message

NeoForgeVersion mcversion cannot be null.

What it means

Final check in NeoForgeVersion.validate(): the Minecraft version this NeoForge build targets (`mcVersion`) must be non-null. Without it, HMCL can't map the NeoForge version to a game version, so the entry is rejected with JsonParseException.

Solutions

1. Refresh the version list / clear mirror cache.
2. Switch mirror or metadata source.
3. Retry later while the mirror completes its sync.
4. Update HMCL if the metadata schema changed.

Example fix

// Not caller-fixable; retry with another source:
versionList.clearCache(mcVersion);
versionList.loadVersionsAsync(mcVersion); // after switching mirror

if (entry.get("mcversion") == null || entry.get("mcversion").isJsonNull()) skip();

if (version.getMcVersion() == null) continue;

try { versionList.loadVersions(mcVersion); }
catch (JsonParseException e) { UI.toast("Mirror metadata incomplete; retrying with official source"); }

When it happens

Trigger: A BMCLAPI metadata entry lacking the Minecraft version field, validated during NeoForge version list loading for a specific mcVersion.

Common situations: Incomplete mirror metadata for brand-new NeoForge builds; schema drift in the BMCLAPI response; corrupted cached version JSON.

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 rawVersion 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/a5c3d515d046f6d0. Report an issue: GitHub.

Appendix: source

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

        @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)