HMCL-dev/HMCL · error · JsonParseException

Theme contrast value must be between -1 and 1:

Error message

Theme contrast value must be between -1 and 1: 

What it means

Thrown by readContrastValue() (invoked from readContrast) when the theme's contrast setting parses to a numeric value outside the accepted [-1, 1] range. Contrast adjusts text/background emphasis, so values beyond this range would produce invalid rendering results. The input at fault is the theme manifest's contrast field value.

Solutions

1. Set the theme's contrast value to a number within -1 to 1, or use a named level (low/standard/medium/high).
2. Clamp parsed contrast values to [-1, 1] before passing them to Contrast resolution.
3. Remove the contrast field to use the default.

When it happens

Trigger: Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemeAppearance.java:354 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemeAppearance.java:354

    /// Reads an optional string field.
    private static @Nullable String readString(JsonObject object, String field) {
        JsonElement element = object.get(field);
        if (element == null) {
            return null;
        }
        if (!(element instanceof JsonPrimitive primitive) || !primitive.isString()) {
            throw new JsonParseException("Theme field must be a string: " + field);
        }
        return primitive.getAsString();
    }

    /// Returns a validated contrast value.
    private static Contrast readContrastValue(double value) {
        try {
            return Contrast.of(value);
        } catch (IllegalArgumentException e) {
            throw new JsonParseException("Theme contrast value must be between -1 and 1: " + value, e);
        }
    }

    /// Adds a canonical contrast value to a JSON object.
    private static void addContrast(JsonObject object, Contrast contrast) {
        if (contrast.equals(Contrast.LOW)) {
            object.addProperty(FIELD_CONTRAST, "low");
        } else if (contrast.equals(Contrast.DEFAULT)) {
            object.addProperty(FIELD_CONTRAST, "standard");
        } else if (contrast.equals(Contrast.MEDIUM)) {
            object.addProperty(FIELD_CONTRAST, "medium");
        } else if (contrast.equals(Contrast.HIGH)) {
            object.addProperty(FIELD_CONTRAST, "high");
        } else {
            object.addProperty(FIELD_CONTRAST, contrast.getValue());
        }
    }

View on GitHub (pinned to 24702dc5a0)