HMCL-dev/HMCL · error · IllegalArgumentException

Launcher background opacity must be between 0 and 1:

Error message

Launcher background opacity must be between 0 and 1: 

What it means

Thrown by the compact constructor of the LauncherBackground record when the supplied opacity is outside the [0, 1] range (or not a finite double). It is an invariant guard for the record: the rendering node applies opacity directly, so out-of-range values would produce undefined JavaFX behavior. The input at fault is an opacity value parsed from a launcher theme/skin configuration.

Solutions

1. Fix the theme file so the opacity setting is a number between 0 and 1 inclusive.
2. Clamp the parsed value before constructing LauncherBackground, e.g. Math.max(0, Math.min(1, opacity)).
3. If the opacity is missing or unparsable, fall back to a default value such as 1.0.

When it happens

Trigger: Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/LauncherBackground.java:35 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/9e4b8433c311a84f. Report an issue: GitHub.

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/LauncherBackground.java:35

 */
package org.jackhuang.hmcl.theme;

import javafx.scene.layout.Background;
import org.jetbrains.annotations.NotNullByDefault;

import java.util.Objects;

/// A launcher background and the opacity applied by its rendering node.
///
/// @param background the JavaFX background rendered by the launcher
/// @param opacity     the node opacity in the range `[0, 1]`
@NotNullByDefault
public record LauncherBackground(Background background, double opacity) {
    /// Creates a launcher background value.
    public LauncherBackground {
        Objects.requireNonNull(background);
        if (!Double.isFinite(opacity) || opacity < 0.0 || opacity > 1.0) {
            throw new IllegalArgumentException("Launcher background opacity must be between 0 and 1: " + opacity);
        }
    }

}

View on GitHub (pinned to 24702dc5a0)