HMCL-dev/HMCL · error · JsonParseException

Theme-pack manifest is missing name

Error message

Theme-pack manifest is missing name

What it means

deserialize requires a "name" member that unmarshals to a non-null LocalizedText; when the member is absent, JSON null, or deserializes to null, JsonParseException "Theme-pack manifest is missing name" is thrown. Unlike description, name is mandatory because every theme pack needs a display name.

Solutions

  1. Add a valid "name" member to theme_pack.json, either a plain string or the localized map form.
  2. If a localization tool emitted null, fix its export so name is serialized.
  3. Repack the zip after editing and retry the load.

Example fix

// before
{ "id": "x", "version": "1.0.0" }
// after
{ "id": "x", "version": "1.0.0", "name": "My Theme" }
Defensive patterns

Strategy: validation

Validate before calling

boolean hasName = obj.has("name") && !obj.get("name").isJsonNull() && (obj.get("name").isJsonPrimitive() || obj.get("name").isJsonObject());

Try / catch

try { ThemePackManifest m = parse(json); } catch (JsonParseException e) { reportMissingField("name"); }

Prevention

When it happens

Trigger: Manifest without a "name" key; "name": null; or a name value that the LocalizedText deserializer rejects/turns into null (e.g. wrong shape instead of string or {zh_CN:...}-style map).

Common situations: Stripping fields while editing a pack; a localization tool that wrote an empty name object; template manifests with name left as a placeholder null.

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/566c08c2aed8b3ba. Report an issue: GitHub.

Appendix: source

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

                @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);
                description = null;
            }

            List<ThemePackAuthor> authors;
            try {
                authors = ThemePackAuthor.parseAuthors(object.get("authors"));
            } catch (JsonParseException | IllegalArgumentException e) {
                LOG.warning("Ignored invalid theme-pack authors", e);

View on GitHub (pinned to 24702dc5a0)