HMCL-dev/HMCL · error · JsonParseException

Theme override must define an object condition

Error message

Theme override must define an object condition

What it means

A theme override object must contain a 'condition' field that is itself a JSON object. If the field is missing, null, a primitive, or an array, JsonParseException("Theme override must define an object condition") is thrown, because ThemeCondition.fromJson expects an object.

Solutions

1. Add a condition object to the override, e.g. "condition": { ... }
2. Fix the field name/key spelling so it matches the loader's expected condition field
3. If the override should always apply, use an empty object {} as the condition if the schema allows

Example fix

// before
{ "darker": 5 }
// after
{ "condition": { "os": "windows" }, "darker": 5 }

static boolean hasCondition(JsonObject override) {
    return override.has("condition") && override.get("condition").isJsonObject();
}

static boolean hasObjectField(JsonObject o, String field) {
    return o.get(field) instanceof JsonObject;
}

try {
    ThemeOverride o = ThemeOverride.fromJson(el);
} catch (JsonParseException e) {
    log.warn("Skipping override: " + e.getMessage());
}

When it happens

Trigger: Calling ThemeOverride.fromJson with an object lacking FIELD_CONDITION or where the condition value is not a JsonObject (string, array, null).

Common situations: Hand-authored theme packs omit the condition block, misspell the 'condition' key, or encode the condition as a string expression.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Invalid theme override
• Theme color must be a string or object
• Unsupported theme color source:
• Theme condition array is empty:
• Theme condition array must contain strings:

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemeOverride.java:64

        }
    }

    /// Parses a theme override from JSON.
    ///
    /// @param element the override object
    /// @return the parsed override
    /// @throws JsonParseException if the override is malformed
    static @Nullable ThemeOverride fromJson(@Nullable JsonElement element) throws JsonParseException {
        if (element == null || element.isJsonNull())
            return null;

        if (!(element instanceof JsonObject object)) {
            throw new JsonParseException("Invalid theme override");
        }

        JsonElement conditionElement = object.get(FIELD_CONDITION);
        if (!(conditionElement instanceof JsonObject conditionObject)) {
            throw new JsonParseException("Theme override must define an object condition");
        }

        ThemeCondition condition = ThemeCondition.fromJson(conditionObject);
        ThemeAppearance appearance = ThemeAppearance.fromJson(object);
        if (appearance.isEmpty()) {
            throw new JsonParseException("Theme override does not define any appearance fields");
        }
        return new ThemeOverride(condition, appearance);
    }

    /// Returns whether this override matches the given resolution context.
    ///
    /// @param context the context to test
    /// @return `true` when the override should be applied
    public boolean matches(ThemeResolveContext context) {
        return condition.matches(context);
    }

View on GitHub (pinned to 24702dc5a0)