HMCL-dev/HMCL · error · IllegalArgumentException

Resolved background built-in wallpaper ID is blank

Error message

Resolved background built-in wallpaper ID is blank

What it means

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.

Solutions

1. Set a real built-in wallpaper ID, e.g. {"builtin": "default"}.
2. Remove the empty builtin field and use a different background type (e.g. a file-based background).
3. Trim/validate the ID in your manifest-generation code before writing it.
4. Pick one of the IDs the launcher registers as built-in wallpapers.

Example fix

// before (theme.json)
{"background": {"type": "builtin", "builtin": ""}}
// after
{"background": {"type": "builtin", "builtin": "default"}}

String id = bg.builtinBackgroundId();
if (id != null && id.trim().isEmpty()) throw new IllegalArgumentException("Blank builtin background id");

try { new ResolvedBackground(type, id, opacity); } catch (IllegalArgumentException e) { if (e.getMessage().endsWith("blank")) id = "default"; else throw e; }

When it happens

Trigger: 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": " "}.

Common situations: 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.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• The author name cannot be empty
• Cannot export a background directory as a theme-pack asset
• Empty theme condition context value
• Localized text cannot be empty object
• ${messagePrefix}${value}

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java:322

            this(type, builtinBackgroundId, imagePath, null, networkImageUrl, networkImageCachePolicy, paint, opacity);
        }

        /// Creates a resolved launcher background.
        ///
        /// @param type                    the launcher background source type
        /// @param builtinBackgroundId     the selected built-in wallpaper ID, or `null` when not using a built-in wallpaper
        /// @param imagePath               the resolved local image file or directory, or `null` when not using a local image
        /// @param imageResource           the resolved theme-pack image resource, or `null` when not using a theme-pack image
        /// @param networkImageUrl         the remote image URL, or `null` when not using a network image
        /// @param networkImageCachePolicy whether the remote image cache policy is explicitly overridden, or `null` for default behavior
        /// @param paint                   the resolved background paint, or `null` when not using a paint background
        /// @param opacity                 the background opacity clamped to `[0, 1]`
        public ResolvedBackground {
            Objects.requireNonNull(type);
            if (builtinBackgroundId != null) {
                builtinBackgroundId = builtinBackgroundId.trim();
                if (builtinBackgroundId.isEmpty()) {
                    throw new IllegalArgumentException("Resolved background built-in wallpaper ID is blank");
                }
            }
            opacity = Double.isFinite(opacity)
                    ? MathUtils.clamp(opacity, 0.0, 1.0)
                    : 1.0;
        }

        /// Returns a copy with a different opacity.
        public ResolvedBackground withOpacity(double opacity) {
            return new ResolvedBackground(
                    type,
                    builtinBackgroundId,
                    imagePath,
                    imageResource,
                    networkImageUrl,
                    networkImageCachePolicy,
                    paint,
                    opacity);

View on GitHub (pinned to 24702dc5a0)