HMCL-dev/HMCL · error · JsonParseException

ForgeVersion files cannot be null

Error message

ForgeVersion files cannot be null

What it means

ForgeBMCLVersionList's ForgeVersion.validate() throws JsonParseException when the 'files' array parsed from the BMCLAPI Forge version list is null. The library treats a version entry without file entries as unusable metadata.

Solutions

1. Fix or regenerate the version-list JSON so each version includes a non-null 'files' array
2. Catch JsonParseException and skip invalid version entries in the list
3. Switch to a different Forge mirror/source (e.g. official Forge promotions JSON)

Example fix

// before
version.validate(); // throws if files == null
// after
try {
    version.validate();
} catch (JsonParseException e) {
    LOG.warning("Skipping invalid Forge version: " + e.getMessage());
}

if (versionObject.get("files") == null || !versionObject.get("files").isJsonArray())
    throw new JsonParseException("ForgeVersion files missing or not an array");

static boolean hasFiles(JsonObject entry) {
    return entry.get("files") instanceof JsonArray;
}

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

When it happens

Trigger: Parsing a BMCLAPI Forge version list JSON where a version object omits the 'files' field, then invoking validate().

Common situations: BMCLAPI mirror returning trimmed/partial data, schema drift in the forge version list API, or hand-crafted test JSON missing 'files'.

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
• 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/bbf25984ae9cff81. Report an issue: GitHub.

Appendix: source

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

        @Nullable
        public String getModified() {
            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;

View on GitHub (pinned to 24702dc5a0)