{"record":{"id":"ab959144efb14caf","repo":"HMCL-dev/HMCL","slug":"theme-condition-value-must-be-a-string-or-string-a","errorCode":null,"errorMessage":"Theme condition value must be a string or string array: ","messagePattern":"Theme condition value must be a string or string array: ","errorType":"validation","errorClass":"JsonParseException","httpStatus":null,"severity":"error","filePath":"HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemeCondition.java","lineNumber":149,"sourceCode":"\n    /// Reads one condition field value.\n    private static Set<String> readAcceptedValues(String key, JsonElement element) throws JsonParseException {\n        LinkedHashSet<String> values = new LinkedHashSet<>();\n        if (element instanceof JsonPrimitive primitive && primitive.isString()) {\n            values.add(normalizeValue(key, primitive.getAsString()));\n        } else if (element instanceof JsonArray array) {\n            if (array.isEmpty()) {\n                throw new JsonParseException(\"Theme condition array is empty: \" + key);\n            }\n\n            for (JsonElement item : array) {\n                if (!(item instanceof JsonPrimitive primitive) || !primitive.isString()) {\n                    throw new JsonParseException(\"Theme condition array must contain strings: \" + key);\n                }\n                values.add(normalizeValue(key, primitive.getAsString()));\n            }\n        } else {\n            throw new JsonParseException(\"Theme condition value must be a string or string array: \" + key);\n        }\n        return values;\n    }\n\n    /// Normalizes and validates a condition key.\n    private static String normalizeKey(String key) {\n        Objects.requireNonNull(key);\n\n        String normalized = key.trim();\n        if (normalized.isEmpty()) {\n            throw new JsonParseException(\"Theme condition key is blank\");\n        }\n        return normalized;\n    }\n\n    /// Normalizes and validates one condition value.\n    private static String normalizeValue(String key, String value) {\n        Objects.requireNonNull(key);","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemeCondition.java#L131-L167","documentation":"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.","triggerScenarios":"ThemeCondition.fromJson encountering {\"os\": 1}, {\"os\": true}, {\"os\": {\"name\":\"windows\"}}, or {\"os\": null} — the element is neither a string primitive nor a JsonArray.","commonSituations":"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.","solutions":["Change the condition value to a string, e.g. \"os\": \"windows\", or a string array, e.g. \"os\": [\"windows\"].","Wrap object-shaped values: use the array of the object's accepted string values instead of the object itself.","Pre-validate theme JSON types before fromJson (value must be JsonPrimitive-string or JsonArray).","Catch JsonParseException and show the user which condition field has an invalid type."],"exampleFix":"// before (theme.json)\n// \"os\": { \"name\": \"windows\" }\n// after\n\"os\": [\"windows\"]","handlingStrategy":"type-guard","validationCode":"JsonElement v = obj.get(key);\nboolean ok = (v instanceof JsonPrimitive p && p.isString()) || v instanceof JsonArray;","typeGuard":"static boolean isValidConditionValue(JsonElement e) {\n    return (e instanceof JsonPrimitive p && p.isString()) || e instanceof JsonArray;\n}","tryCatchPattern":"try {\n    ThemeCondition c = ThemeCondition.fromJson(element);\n} catch (JsonParseException e) {\n    LOG.warning(\"Condition value has wrong JSON type: \" + e.getMessage());\n}","preventionTips":["Condition values must be a string or an array of strings — nothing else","Validate value types with a JSON schema before fromJson","When porting themes from other formats, map object values to string arrays","Check theme files edited by hand for wrong JSON types"],"tags":["json","theme","type-mismatch","condition"],"backgroundTag":"invalid-argument-format","analyzedSha":"24702dc5a0214034f4c27166d5fd30cad08cec19","analyzedAt":"2026-09-10T12:36:46.680Z","contentChangedAt":"2026-09-10T12:36:46.680Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}