HMCL-dev/HMCL · error · JsonParseException

Unsupported theme-pack schema

Error message

Unsupported theme-pack schema: ${schema}

What it means

After confirming the manifest is a JsonObject, deserialize checks it against CURRENT_SCHEMA via JsonSchema.check; if the schema is not "readable" (schema property missing or an incompatible version), it throws JsonParseException naming the schema value found in the manifest. This gates packs written for older/newer manifest formats.

Solutions

  1. Update HMCL to a version whose CURRENT_SCHEMA can read the pack's declared schema.
  2. Set the manifest's "schema" field to the value supported by your HMCL build (see CURRENT_SCHEMA).
  3. If the schema value is garbage/non-string, fix it to the expected version string and repack.

Example fix

// before
"schema": 2
// after
"schema": "1"
Defensive patterns

Strategy: try-catch

Validate before calling

String schema = obj.has("schema") && obj.get("schema").isJsonPrimitive() ? obj.get("schema").getAsString() : null;

Try / catch

try { return deserializeManifest(object); } catch (JsonParseException e) { promptUserToUpdateHMCL(); }

Prevention

When it happens

Trigger: A manifest with "schema" set to an unsupported version string, a non-string schema value (JsonElement is interpolated, so it may print as "..."), or the schema property omitted entirely.

Common situations: Opening a theme pack produced by a newer HMCL version than the running one; hand-written manifests missing the schema field; schema copied from another pack format.

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

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManifest.java:278

        return id;
    }

    static final class Adapter implements JsonSerializer<@Nullable ThemePackManifest>,
            JsonDeserializer<@Nullable ThemePackManifest> {

        @Override
        public @Nullable ThemePackManifest deserialize(
                @Nullable JsonElement json, Type typeOfT, JsonDeserializationContext context) throws JsonParseException {
            if (json == null || json instanceof JsonNull) {
                return null;
            }

            if (!(json instanceof JsonObject object)) {
                throw new JsonParseException("Theme-pack manifest is not a JsonObject");
            }

            if (!JsonSchema.check(object, CURRENT_SCHEMA).readable()) {
                throw new JsonParseException("Unsupported theme-pack schema: " + object.get(JsonSchema.PROPERTY_SCHEMA));
            }

            String id = requireMemberString(object, "id");
            String version = requireMemberString(object, "version");

            LocalizedText name = context.deserialize(object.get("name"), LocalizedText.class);
            if (name == null) {
                throw new JsonParseException("Theme-pack manifest is missing name");
            }

            @Nullable LocalizedText description;
            try {
                description = context.deserialize(object.get("description"), LocalizedText.class);
                if (description != null) {
                    description = requireLocalizedText(description, "description");
                }
            } catch (JsonParseException | IllegalArgumentException e) {
                LOG.warning("Ignored invalid theme-pack description", e);

View on GitHub (pinned to 24702dc5a0)