{"record":{"id":"69ccb5ed23686112","repo":"HMCL-dev/HMCL","slug":"resolved-background-built-in-wallpaper-id-is-blank","errorCode":null,"errorMessage":"Resolved background built-in wallpaper ID is blank","messagePattern":"Resolved background built-in wallpaper ID is blank","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java","lineNumber":322,"sourceCode":"            this(type, builtinBackgroundId, imagePath, null, networkImageUrl, networkImageCachePolicy, paint, opacity);\n        }\n\n        /// Creates a resolved launcher background.\n        ///\n        /// @param type                    the launcher background source type\n        /// @param builtinBackgroundId     the selected built-in wallpaper ID, or `null` when not using a built-in wallpaper\n        /// @param imagePath               the resolved local image file or directory, or `null` when not using a local image\n        /// @param imageResource           the resolved theme-pack image resource, or `null` when not using a theme-pack image\n        /// @param networkImageUrl         the remote image URL, or `null` when not using a network image\n        /// @param networkImageCachePolicy whether the remote image cache policy is explicitly overridden, or `null` for default behavior\n        /// @param paint                   the resolved background paint, or `null` when not using a paint background\n        /// @param opacity                 the background opacity clamped to `[0, 1]`\n        public ResolvedBackground {\n            Objects.requireNonNull(type);\n            if (builtinBackgroundId != null) {\n                builtinBackgroundId = builtinBackgroundId.trim();\n                if (builtinBackgroundId.isEmpty()) {\n                    throw new IllegalArgumentException(\"Resolved background built-in wallpaper ID is blank\");\n                }\n            }\n            opacity = Double.isFinite(opacity)\n                    ? MathUtils.clamp(opacity, 0.0, 1.0)\n                    : 1.0;\n        }\n\n        /// Returns a copy with a different opacity.\n        public ResolvedBackground withOpacity(double opacity) {\n            return new ResolvedBackground(\n                    type,\n                    builtinBackgroundId,\n                    imagePath,\n                    imageResource,\n                    networkImageUrl,\n                    networkImageCachePolicy,\n                    paint,\n                    opacity);","sourceCodeStart":304,"sourceCodeEnd":340,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java#L304-L340","documentation":"Thrown by the ResolvedBackground compact constructor in ThemePackManager when a built-in wallpaper reference is present but trims to an empty string. A resolved background claiming type built-in must identify a wallpaper; blank IDs are rejected to keep resolution deterministic.","triggerScenarios":"Constructing ResolvedBackground with a type of built-in wallpaper and builtinBackgroundId set to \"\" or whitespace-only, e.g. from a manifest background entry like {\"builtin\": \"   \"}.","commonSituations":"Manifests where the builtin background id was cleared but the key kept, templates with empty placeholder ids, or user-edited theme settings that blanked the wallpaper field.","solutions":["Set a real built-in wallpaper ID, e.g. {\"builtin\": \"default\"}.","Remove the empty builtin field and use a different background type (e.g. a file-based background).","Trim/validate the ID in your manifest-generation code before writing it.","Pick one of the IDs the launcher registers as built-in wallpapers."],"exampleFix":"// before (theme.json)\n{\"background\": {\"type\": \"builtin\", \"builtin\": \"\"}}\n// after\n{\"background\": {\"type\": \"builtin\", \"builtin\": \"default\"}}","handlingStrategy":"validation","validationCode":"String id = bg.builtinBackgroundId();\nif (id != null && id.trim().isEmpty()) throw new IllegalArgumentException(\"Blank builtin background id\");","typeGuard":null,"tryCatchPattern":"try { new ResolvedBackground(type, id, opacity); } catch (IllegalArgumentException e) { if (e.getMessage().endsWith(\"blank\")) id = \"default\"; else throw e; }","preventionTips":["Trim and check builtin IDs when reading manifests","Use a known built-in wallpaper ID like \"default\"","Omit the builtin field entirely when using another background type"],"tags":["theme-pack","background","empty-value","validation"],"backgroundTag":"empty-required-field","analyzedSha":"24702dc5a0214034f4c27166d5fd30cad08cec19","analyzedAt":"2026-09-10T12:36:46.680Z","contentChangedAt":"2026-09-10T12:36:46.680Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}