HMCL-dev/HMCL · error · IllegalArgumentException

Theme-pack manifest field is blank

Error message

Theme-pack manifest field is blank: ${field}

What it means

Thrown by ThemePackManifest.requireNonBlank when a required theme-pack manifest field (id, version, name text, etc.) is null-or-whitespace after trimming. The manifest parser rejects packs whose metadata fields are empty so downstream code never deals with blank identifiers or display names. It surfaces as IllegalArgumentException during manifest parsing.

Solutions

1. Open the pack's theme_pack.json and fill in the blank field named in the message (e.g. "id", "version").
2. Re-validate the manifest against CURRENT_SCHEMA after editing, then repack the zip.
3. If fields are generated by a script, ensure the source variables are non-empty before substitution.

Example fix

// before
"version": ""
// after
"version": "1.0.0"

boolean ok = manifest.optString("id", "").isBlank() || manifest.optString("version", "").isBlank() ? false : true;

try { ThemePackManifest m = parse(json); } catch (IllegalArgumentException e) { showUserFriendlyMessage(e.getMessage()); }

When it happens

Trigger: Parsing a theme-pack manifest whose "id", "version", or localized name string is "", " ", or whitespace-only; requireMemberString/parseLocalizedText feed raw JSON strings into requireNonBlank.

Common situations: Hand-edited theme_pack.json with an emptied field; a packaging script that substituted an unset variable into the manifest; copying a manifest template and forgetting to fill in the id.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Theme-pack author must be an object or a string
• Theme packs cannot reference built-in wallpaper
• Theme pack value is missing
• Theme pack must declare at least one theme
• Theme-pack manifest is missing themes array

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

Appendix: source

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

            }
            return new LocalizedText(localizedValues);
        }
        throw new JsonParseException("Theme-pack localized text must be a string or object: " + field);
    }

    /// Returns a validated localized text value.
    static LocalizedText requireLocalizedText(LocalizedText value, String field) {
        Objects.requireNonNull(value);

        JsonElement element = JsonUtils.GSON.toJsonTree(value, LocalizedText.class);
        return parseLocalizedText(element, field);
    }

    /// Returns a non-blank string value.
    private static String requireNonBlank(String value, String field) {
        String trimmed = value.trim();
        if (trimmed.isEmpty()) {
            throw new IllegalArgumentException("Theme-pack manifest field is blank: " + field);
        }
        return trimmed;
    }

    /// Returns a package ID matching the theme-pack ID format.
    static String requirePackageId(String value) {
        return requireId(value, "id", "Theme-pack manifest ID must follow package ID format: ");
    }

    /// Returns a theme ID matching the theme-pack ID format.
    static String requireThemeId(String value) {
        return requireId(value, "theme id", "Theme ID must follow package ID format: ");
    }

    /// Returns an ID matching the theme-pack ID format.
    private static String requireId(String value, String field, String messagePrefix) {
        String id = requireNonBlank(value, field);
        if (!PACKAGE_ID_PATTERN.matcher(id).matches()) {

View on GitHub (pinned to 24702dc5a0)