HMCL-dev/HMCL · error · JsonParseException

Processor::jar cannot be null

Error message

Processor::jar cannot be null

What it means

The nested Processor.validate() throws JsonParseException when a processor entry in install_profile.json has no 'jar' field. Every Forge processor must name the JAR artifact containing its main class; without it HMCL cannot run the processor. Thrown during profile deserialization validation.

Solutions

  1. Re-download the official Forge installer matching the desired game version
  2. Inspect install_profile.json inside the installer and confirm every processors[] entry has a 'jar' field
  3. Report the profile to HMCL if a legitimately new Forge format omits 'jar' (schema change needing launcher support)
  4. Use a different Forge version whose installer profile is known to work with this HMCL version

Example fix

// before: hand-edited profile processor entry
{"channels": ["extract"], "outputs": {...}}
// after
{"jar": "net.minecraftforge:installertools:1.3.0", "classpath": [...], "args": [...], "outputs": {...}}
Defensive patterns

Strategy: validation

Validate before calling

// Validate processors before installation
try (FileSystem fs = CompressingUtils.createReadOnlyZipFileSystem(installer)) {
    JsonObject profile = JsonParser.parseString(Files.readString(fs.getPath("install_profile.json"))).getAsJsonObject();
    JsonArray processors = profile.getAsJsonArray("processors");
    for (JsonElement p : processors)
        if (p.getAsJsonObject().get("jar") == null) throw new IOException("Processor without jar in profile");
}

Try / catch

try {
    task.run();
} catch (JsonParseException e) {
    // treat installer as corrupt: re-download and retry once
}

Prevention

When it happens

Trigger: Parsing an install_profile.json whose 'processors' array contains an entry missing the 'jar' key (or where Gson left it null), during ForgeNewInstallTask profile loading.

Common situations: Corrupted or hand-edited installer profiles; a Forge installer version whose processor schema HMCL does not fully understand; truncated installer downloads.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/download/forge/ForgeNewInstallProfile.java:195

            return args == null ? Collections.emptyList() : args;
        }

        /**
         * File-checksum pairs, used for verifying the output file is correct.
         * Arguments to pass to the processor jar.
         * Keys can be in one of [artifact] or {entry}. Should be file path.
         * Values can be in one of {entry} or 'literal'. Should be SHA-1 checksum.
         * @return files output from this processor.
         * @see ForgeNewInstallTask#parseLiteral(String, Map, ExceptionalFunction)
         */
        public Map<String, String> getOutputs() {
            return outputs == null ? Collections.emptyMap() : outputs;
        }

        @Override
        public void validate() throws JsonParseException, TolerableValidationException {
            if (jar == null)
                throw new JsonParseException("Processor::jar cannot be null");
        }
    }

    public static class Datum {
        private final String client;

        public Datum(String client) {
            this.client = client;
        }

        /**
         * Can be in the following formats:
         * [value]: An artifact path.
         * 'value': A string literal.
         * value: A file in the installer package, to be extracted to a temp folder, and then have the absolute path in replacements.
         * @return Value to use for the client install
         */
        public String getClient() {

View on GitHub (pinned to 24702dc5a0)