HMCL-dev/HMCL · error · JsonParseException

Theme condition value must be a string or string array:

Error message

Theme condition value must be a string or string array: 

What it means

A condition field's JSON value must be either a single JSON string or an array of strings. Any other JSON type (number, boolean, object, null, literal) is rejected with this JsonParseException in readAcceptedValues.

Solutions

1. Change the condition value to a string, e.g. "os": "windows", or a string array, e.g. "os": ["windows"].
2. Wrap object-shaped values: use the array of the object's accepted string values instead of the object itself.
3. Pre-validate theme JSON types before fromJson (value must be JsonPrimitive-string or JsonArray).
4. Catch JsonParseException and show the user which condition field has an invalid type.

Example fix

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

JsonElement v = obj.get(key);
boolean ok = (v instanceof JsonPrimitive p && p.isString()) || v instanceof JsonArray;

static boolean isValidConditionValue(JsonElement e) {
    return (e instanceof JsonPrimitive p && p.isString()) || e instanceof JsonArray;
}

try {
    ThemeCondition c = ThemeCondition.fromJson(element);
} catch (JsonParseException e) {
    LOG.warning("Condition value has wrong JSON type: " + e.getMessage());
}

When it happens

Trigger: ThemeCondition.fromJson encountering {"os": 1}, {"os": true}, {"os": {"name":"windows"}}, or {"os": null} — the element is neither a string primitive nor a JsonArray.

Common situations: Hand-edited theme files using the wrong JSON type for a condition; copy-paste from documentation of a different theme format; generators emitting objects where arrays are expected.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Theme condition array must contain strings:
• Theme condition array is empty:
• Theme condition key is blank
• 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/ab959144efb14caf. Report an issue: GitHub.

Appendix: source

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

    /// Reads one condition field value.
    private static Set<String> readAcceptedValues(String key, JsonElement element) throws JsonParseException {
        LinkedHashSet<String> values = new LinkedHashSet<>();
        if (element instanceof JsonPrimitive primitive && primitive.isString()) {
            values.add(normalizeValue(key, primitive.getAsString()));
        } else if (element instanceof JsonArray array) {
            if (array.isEmpty()) {
                throw new JsonParseException("Theme condition array is empty: " + key);
            }

            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);

View on GitHub (pinned to 24702dc5a0)