HMCL-dev/HMCL · error · JsonParseException

Theme condition key is blank

Error message

Theme condition key is blank

What it means

Fires in ThemeCondition.normalizeKey() when a condition object's key is missing or blank. Condition keys drive which theme variant is applied (e.g. system or version conditions), so an unnamed key cannot be normalized or matched and the whole theme manifest fails parsing. The input at fault is a condition entry with an empty or absent key.

Solutions

1. Give the condition field a real key, e.g. "os", "language", or "brightness".
2. Delete the blank-keyed entry from the theme JSON or requirements map.
3. Trim/default keys before constructing the map; skip entries whose trimmed key is empty.
4. Catch JsonParseException around fromJson and report the malformed condition entry to the user.

Example fix

// before (theme.json)
// "conditions": { "": ["windows"] }
// after
"conditions": { "os": ["windows"] }

boolean ok = key != null && !key.trim().isEmpty();

static boolean isNotBlankKey(String k) {
    return k != null && !k.trim().isEmpty();
}

try {
    ThemeCondition c = ThemeCondition.fromJson(element);
} catch (JsonParseException e) {
    LOG.warning("Theme has a blank condition key: " + e.getMessage());
}

When it happens

Trigger: Building a ThemeCondition from a map with a key like "" or " ", or from JSON object entries with whitespace-only names — normalizeKey runs on every entry during fromJson.

Common situations: Hand-edited theme JSON with an unnamed condition field; string concatenation producing empty keys; generators emitting placeholder keys that collapse to empty after trimming.

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 condition array is empty:
• Theme condition array must contain strings:
• Theme condition value must be a string or string array:
• Empty theme condition value for
• Unsupported brightness condition value:

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemeCondition.java:160

            for (JsonElement item : array) {
                if (!(item instanceof JsonPrimitive primitive) || !primitive.isString()) {
                    throw new JsonParseException("Theme condition array must contain strings: " + key);
                }
                values.add(normalizeValue(key, primitive.getAsString()));
            }
        } else {
            throw new JsonParseException("Theme condition value must be a string or string array: " + key);
        }
        return values;
    }

    /// Normalizes and validates a condition key.
    private static String normalizeKey(String key) {
        Objects.requireNonNull(key);

        String normalized = key.trim();
        if (normalized.isEmpty()) {
            throw new JsonParseException("Theme condition key is blank");
        }
        return normalized;
    }

    /// Normalizes and validates one condition value.
    private static String normalizeValue(String key, String value) {
        Objects.requireNonNull(key);
        Objects.requireNonNull(value);

        String trimmed = value.trim();
        if (trimmed.isEmpty()) {
            throw new JsonParseException("Empty theme condition value for " + key);
        }
        String normalized = trimmed.toLowerCase(Locale.ROOT);

        return switch (key) {
            case KEY_BRIGHTNESS -> switch (normalized) {
                    case "light", "dark" -> normalized;

View on GitHub (pinned to 24702dc5a0)