HMCL-dev/HMCL · error · JsonParseException

Theme ID must follow package ID format:

Error message

Theme ID must follow package ID format: 

What it means

Thrown in Theme.fromJson() when the theme declares an 'id' that does not conform to the theme-pack ID format enforced by ThemePackManifest.requireThemeId(). The ID is used for stable references and overrides between themes, so a malformed identifier (wrong characters or structure) fails parsing. The input at fault is the theme's 'id' JSON string.

Solutions

1. Change the theme 'id' in the manifest to match the package ID format (typically lowercase letters, digits, hyphens/underscores, no spaces).
2. Regenerate or correct the theme pack manifest so the id satisfies ThemePackManifest.requireThemeId.
3. Remove the id field if the pack is a single unnamed theme and identity is not required.

When it happens

Trigger: Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/Theme.java:98 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/31aef58302590676. Report an issue: GitHub.

Appendix: source

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

        overrides = List.copyOf(overrides);
    }

    /// Parses a theme from JSON.
    ///
    /// @param object          the theme JSON object
    /// @param requireIdentity whether the theme must declare an explicit ID and name
    /// @return the parsed theme
    /// @throws JsonParseException if required identity fields are missing or malformed
    static Theme fromJson(JsonObject object, boolean requireIdentity) throws JsonParseException {
        Objects.requireNonNull(object);

        @Nullable String id = JsonUtils.getString(object, "id");
        if (id != null) {
            try {
                id = ThemePackManifest.requireThemeId(id);
            } catch (IllegalArgumentException e) {
                if (requireIdentity) {
                    throw new JsonParseException(e);
                }
                LOG.warning("Ignored invalid theme id: " + id, e);
                id = null;
            }
        }
        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;
            }

View on GitHub (pinned to 24702dc5a0)