{"record":{"id":"a62440b1fdb19eb8","repo":"HMCL-dev/HMCL","slug":"theme-background-opacity-must-be-between-0-and-1","errorCode":null,"errorMessage":"Theme background opacity must be between 0 and 1: ","messagePattern":"Theme background opacity must be between 0 and 1: ","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemeBackgroundSettings.java","lineNumber":48,"sourceCode":"\n/// Background settings contributed by a theme-pack appearance.\n///\n/// @param source the background source, or `null` when inherited\n/// @param opacity the background opacity override, or `null` when inherited\n@NotNullByDefault\npublic record ThemeBackgroundSettings(\n        @Nullable ThemeBackground source,\n        @Nullable Double opacity) {\n    /// JSON member name for the background opacity.\n    private static final String FIELD_OPACITY = \"opacity\";\n\n    /// Creates background settings.\n    ///\n    /// @param source the background source, or `null` when inherited\n    /// @param opacity the background opacity override, or `null` when inherited\n    public ThemeBackgroundSettings {\n        if (opacity != null && (opacity < 0.0 || opacity > 1.0 || !Double.isFinite(opacity))) {\n            throw new IllegalArgumentException(\"Theme background opacity must be between 0 and 1: \" + opacity);\n        }\n    }\n\n    /// Parses background settings from a JSON object.\n    ///\n    /// @param object the JSON object\n    /// @return the parsed background settings\n    static ThemeBackgroundSettings fromJson(JsonObject object) throws JsonParseException {\n        Objects.requireNonNull(object);\n\n        return new ThemeBackgroundSettings(\n                ThemeBackground.fromJson(object),\n                readOpacity(object));\n    }\n\n    /// Converts these settings to their JSON representation.\n    ///\n    /// @return the JSON object representing these background settings","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemeBackgroundSettings.java#L30-L66","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nnew ThemeBackgroundSettings(source, 80.0);\n// after\nnew ThemeBackgroundSettings(source, Math.clamp(80.0 / 100.0, 0.0, 1.0));","handlingStrategy":"validation","validationCode":"Double safeOpacity(Double v) {\n    if (v == null) return null;\n    if (!Double.isFinite(v) || v < 0.0 || v > 1.0) return null; // inherit default\n    return v;\n}","typeGuard":"boolean isValidOpacity(double v) {\n    return Double.isFinite(v) && v >= 0.0 && v <= 1.0;\n}","tryCatchPattern":"try { settings = new ThemeBackgroundSettings(source, opacity); } catch (IllegalArgumentException e) { settings = new ThemeBackgroundSettings(source, null); LOG.warning(e.getMessage()); }","preventionTips":["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"],"tags":["validation","range-check","theme-config","illegal-argument"],"backgroundTag":"value-out-of-range","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"}