HMCL-dev/HMCL · error · IllegalArgumentException

Illegal Json-Patch:

Error message

Illegal Json-Patch:

What it means

MultiMCInstancePatch.read wraps JsonParseException thrown while deserializing a MultiMC component patch JSON, rethrowing it as IllegalArgumentException identifying the offending component ID. It indicates the patch text is not valid JSON or does not match the MultiMCInstancePatch schema.

Solutions

  1. Fix or regenerate the offending component JSON identified by componentID
  2. Re-download or re-import the MultiMC instance archive
  3. Validate the JSON with a linter before placing it in the instance

Example fix

// before
String text = "{ not valid json }";
MultiMCInstancePatch.read("net.minecraft", text);
// after
String text = "{\"formatVersion\":1,\"uid\":\"net.minecraft\"}"; // valid patch JSON
MultiMCInstancePatch.read("net.minecraft", text);
Defensive patterns

Strategy: try-catch

Validate before calling

try { JsonUtils.fromNonNullJson(text, MultiMCInstancePatch.class); } catch (JsonParseException e) { /* reject component before calling read */ }

Try / catch

try { patch = MultiMCInstancePatch.read(id, text); } catch (IllegalArgumentException e) { LOG.warning("Bad patch for " + id, e); skipOrAbort(); }

Prevention

When it happens

Trigger: Reading a component JSON file (e.g. from mmc-pack.json or patches/ directory) that is malformed or has an unexpected structure, via MultiMCInstancePatch.read(componentID, text).

Common situations: Corrupted MultiMC/PollyMC instances; hand-edited component files; mmc-pack.json entries with invalid embedded JSON.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/modpack/multimc/MultiMCInstancePatch.java:197

        // TODO: Maybe new ArrayList(new LinkedHashSet(original)) ?

        Set<T> values = new HashSet<>();
        List<T> result = new ArrayList<>();

        for (T item : original) {
            if (values.add(item)) {
                result.add(item);
            }
        }

        return result;
    }

    public static MultiMCInstancePatch read(String componentID, String text) {
        try {
            return JsonUtils.fromNonNullJson(text, MultiMCInstancePatch.class);
        } catch (JsonParseException e) {
            throw new IllegalArgumentException("Illegal Json-Patch: " + componentID);
        }
    }

    public static final class ResolvedInstance {
        private final GameInstanceManifest manifest;

        private final String gameVersion;

        private final Library mainJar;

        private final List<String> jarModFileNames;
        private final List<Library> mavenOnlyFiles;

        public ResolvedInstance(GameInstanceManifest manifest, String gameVersion, Library mainJar, List<String> jarModFileNames, List<Library> mavenOnlyFiles) {
            this.manifest = manifest;
            this.gameVersion = gameVersion;
            this.mainJar = mainJar;
            this.jarModFileNames = jarModFileNames;

View on GitHub (pinned to 24702dc5a0)