{"record":{"id":"db5830b6becdd079","repo":"HMCL-dev/HMCL","slug":"forgeversionroot-number-cannot-be-null","errorCode":null,"errorMessage":"ForgeVersionRoot number cannot be null","messagePattern":"ForgeVersionRoot number cannot be null","errorType":"validation","errorClass":"JsonParseException","httpStatus":null,"severity":"error","filePath":"HMCLCore/src/main/java/org/jackhuang/hmcl/download/forge/ForgeVersionRoot.java","lineNumber":102,"sourceCode":"        return branches;\n    }\n\n    public Map<String, int[]> getGameVersions() {\n        return mcversion;\n    }\n\n    public Map<String, Integer> getPromos() {\n        return promos;\n    }\n\n    public Map<Integer, ForgeVersion> getNumber() {\n        return number;\n    }\n\n    @Override\n    public void validate() throws JsonParseException {\n        if (number == null)\n            throw new JsonParseException(\"ForgeVersionRoot number cannot be null\");\n        if (mcversion == null)\n            throw new JsonParseException(\"ForgeVersionRoot mcversion cannot be null\");\n    }\n\n}\n","sourceCodeStart":84,"sourceCodeEnd":108,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/download/forge/ForgeVersionRoot.java#L84-L108","documentation":"ForgeVersionRoot.validate() throws this JsonParseException when the 'number' field (the Forge build number) is null in the parsed promoter/root JSON. HMCL needs the build number to resolve the concrete Forge installer; the record is unusable without it.","triggerScenarios":"validate() on a ForgeVersionRoot whose source JSON (e.g. https://files.minecraftforge.net promos/versions list) lacked 'number', typically because the lookup for that Minecraft version returned an unexpected structure.","commonSituations":"Requesting a Minecraft version Forge has not published a build for, a mirror returning empty/placeholder entries, or the promoter list format changing.","solutions":["Verify Forge actually publishes a build for the requested Minecraft version before resolving.","Re-fetch the Forge version list JSON from the official source or a different mirror.","Update HMCL to handle the current Forge metadata format."],"exampleFix":"// before\nForgeVersionRoot root = JsonUtils.fromJson(json, ForgeVersionRoot.class);\nroot.validate();\n// after\nForgeVersionRoot root = JsonUtils.fromJson(json, ForgeVersionRoot.class);\nif (root == null || root.getNumber() == null) {\n    throw new UnsupportedGameVersionException(mcVersion); // no Forge build exists\n}\nroot.validate();","handlingStrategy":"validation","validationCode":"if (rootJson == null || !rootJson.has(\"number\")) throw new IllegalStateException(\"No Forge build for \" + mcVersion);","typeGuard":"boolean hasNumber(ForgeVersionRoot r) { return r != null && r.getNumber() != null; }","tryCatchPattern":"try { root.validate(); } catch (JsonParseException e) { fallbackToOtherMirror(); }","preventionTips":["Check Forge availability for the target game version before resolving","Keep HMCL updated for metadata format changes","Fall back to the official Forge meta when mirrors fail"],"tags":["json","forge","validation"],"backgroundTag":"schema-validation-failed","analyzedSha":"24702dc5a0214034f4c27166d5fd30cad08cec19","analyzedAt":"2026-09-10T12:36:46.680Z","contentChangedAt":"2026-09-10T12:36:46.680Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}