What causes "Theme background opacity must be between 0 and 1: " in HMCL-dev/HMCL?

Clamp the value before constructing: Math.max(0.0, Math.min(1.0, opacity))

HMCL-dev/HMCL · error · IllegalArgumentException

Theme background opacity must be between 0 and 1:

Error message

Theme background opacity must be between 0 and 1:

What it means

The ThemeBackgroundSettings compact constructor throws this IllegalArgumentException when the opacity argument is non-null but outside [0.0, 1.0] or not finite (NaN/Infinity). Opacity is a strict 0–1 clamp: any other value makes the record unconstructable. Note the JSON parser (readOpacity) silently ignores invalid JSON opacity values with a warning; this hard exception only fires for programmatic construction.

Solutions

Clamp the value before constructing: Math.max(0.0, Math.min(1.0, opacity))
Convert percentage inputs by dividing by 100 (80 -> 0.8)
Pass null instead of an invalid number to inherit the default opacity
Guard against NaN/Infinity with Double.isFinite before constructing

Example fix

// before
new ThemeBackgroundSettings(source, 80.0);
// after
new ThemeBackgroundSettings(source, Math.clamp(80.0 / 100.0, 0.0, 1.0));

Defensive patterns

Strategy: validation

Validate before calling

Double safeOpacity(Double v) {
    if (v == null) return null;
    if (!Double.isFinite(v) || v < 0.0 || v > 1.0) return null; // inherit default
    return v;
}

Type guard

boolean isValidOpacity(double v) {
    return Double.isFinite(v) && v >= 0.0 && v <= 1.0;
}

Try / catch

try { settings = new ThemeBackgroundSettings(source, opacity); } catch (IllegalArgumentException e) { settings = new ThemeBackgroundSettings(source, null); LOG.warning(e.getMessage()); }

Prevention

Clamp inputs with Math.clamp(v, 0.0, 1.0) before constructing
Divide percentages by 100 before passing them in
Pass null rather than an out-of-range value to inherit the default

When it happens

Trigger: Calling new ThemeBackgroundSettings(source, opacity) in Java with opacity = -0.1, 1.5, Double.NaN, or Double.POSITIVE_INFINITY; also via merge() if a patch record carries such a value.

Common situations: Plugin or custom theme code computing opacity as a percentage (e.g. 80 instead of 0.8) or dividing by zero producing Infinity, then handing the raw double to the constructor.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemeBackgroundSettings.java:48

/// Background settings contributed by a theme-pack appearance.
///
/// @param source the background source, or `null` when inherited
/// @param opacity the background opacity override, or `null` when inherited
@NotNullByDefault
public record ThemeBackgroundSettings(
        @Nullable ThemeBackground source,
        @Nullable Double opacity) {
    /// JSON member name for the background opacity.
    private static final String FIELD_OPACITY = "opacity";

    /// Creates background settings.
    ///
    /// @param source the background source, or `null` when inherited
    /// @param opacity the background opacity override, or `null` when inherited
    public ThemeBackgroundSettings {
        if (opacity != null && (opacity < 0.0 || opacity > 1.0 || !Double.isFinite(opacity))) {
            throw new IllegalArgumentException("Theme background opacity must be between 0 and 1: " + opacity);
        }
    }

    /// Parses background settings from a JSON object.
    ///
    /// @param object the JSON object
    /// @return the parsed background settings
    static ThemeBackgroundSettings fromJson(JsonObject object) throws JsonParseException {
        Objects.requireNonNull(object);

        return new ThemeBackgroundSettings(
                ThemeBackground.fromJson(object),
                readOpacity(object));
    }

    /// Converts these settings to their JSON representation.
    ///
    /// @return the JSON object representing these background settings

View on GitHub (pinned to 24702dc5a0)