HMCL-dev/HMCL · error · JsonParseException

Theme is missing required localized text field: name

Error message

Theme is missing required localized text field: name

What it means

Raised in Theme.fromJson() when a required localized text field — here the 'name' field — is missing or cannot be parsed as LocalizedText, and identity is required. The theme is unusable in the picker without a display name, so parsing aborts instead of logging and continuing (the tolerant branch only applies when requireIdentity is false).

Solutions

1. Add a valid localized 'name' object (e.g. {"en_US": "...", "zh_CN": "..."}) to the theme JSON.
2. Ensure the 'name' value is a JSON object of locale-to-string mappings, not a bare string or null.
3. Re-download the theme pack; the file may be corrupted or truncated.

When it happens

Trigger: Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/Theme.java:121 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/Theme.java:121

        }
        if (id == null && requireIdentity) {
            throw new JsonParseException("Theme is missing the id");
        }
        @Nullable LocalizedText name;
        try {
            name = LocalizedText.fromJson(object.get("name"));
            if (name != null && name.mayBeEmpty()) {
                throw new JsonParseException("Theme name is empty: " + name);
            }
        } catch (JsonParseException | IllegalArgumentException e) {
            if (requireIdentity) {
                throw e;
            }
            LOG.warning("Ignored invalid theme name", e);
            name = null;
        }
        if (name == null && requireIdentity) {
            throw new JsonParseException("Theme is missing required localized text field: " + "name");
        }

        List<ThemePackAuthor> authors;
        try {
            authors = ThemePackAuthor.parseAuthors(object.get("authors"));
        } catch (Exception e) {
            LOG.warning("Failed to parse authors", e);
            authors = List.of();
        }

        @Nullable LocalizedText description;

        try {
            description = LocalizedText.fromJson(object.get("description"));
            if (description != null) {
                description = ThemePackManifest.requireLocalizedText(description, "description");
            }
        } catch (Exception e) {

View on GitHub (pinned to 24702dc5a0)