HMCL-dev/HMCL · error · JsonParseException

ServerModpackManifest.files cannot be null

Error message

ServerModpackManifest.files cannot be null

What it means

Validation error thrown when a server modpack manifest (modpack.json) lacks the 'files' array. The manifest must list every file of the pack; without it the client cannot know what to download, so the manifest is rejected.

Solutions

1. Add a 'files' array with FileInformation entries (path, hash, size) to the manifest.
2. Regenerate the manifest with the HMCL server modpack export task or a maintained tool.
3. Re-download modpack.json if the local copy is truncated or corrupted.

Example fix

// before
{ "fileApi": "https://example.com/files" }
// after
{ "fileApi": "https://example.com/files", "files": [{"path": "mods/a.jar", "hash": "...", "size": 123}] }

JsonObject manifest = JsonUtils.fromJson(json, JsonObject.class);
if (!manifest.has("files") || !manifest.get("files").isJsonArray())
    throw new JsonParseException("manifest missing files");

try {
    manifest.validate();
} catch (JsonParseException e) {
    if (e.getMessage().contains("files cannot be null")) {
        // regenerate or re-download the manifest
    }
}

When it happens

Trigger: ServerModpackManifest.validate() runs after deserialization and the 'files' key is absent or null in the manifest JSON.

Common situations: Manually crafted manifests missing the files list; broken manifest generators; corrupted/partial downloads of modpack.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

• MinecraftInstanceConfiguration missing `manifest`
• MinecraftInstanceConfiguration missing `type`
• ServerModpackManifest.fileApi cannot be blank
• FileInformation missing `path`.
• FileInformation missing file hash code.

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/modpack/server/ServerModpackManifest.java:99

    public List<ModpackConfiguration.FileInformation> getFiles() {
        return files;
    }

    public List<Addon> getAddons() {
        return addons;
    }

    @Override
    public ModpackProvider getProvider() {
        return ServerModpackProvider.INSTANCE;
    }

    @Override
    public void validate() throws JsonParseException, TolerableValidationException {
        if (fileApi == null)
            throw new JsonParseException("ServerModpackManifest.fileApi cannot be blank");
        if (files == null)
            throw new JsonParseException("ServerModpackManifest.files cannot be null");
    }

    public static final class Addon {
        private final String id;
        private final String version;

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

        public Addon(String id, String version) {
            this.id = id;
            this.version = version;
        }

        public String getId() {
            return id;
        }

View on GitHub (pinned to 24702dc5a0)