HMCL-dev/HMCL · error · JsonParseException

Theme background field is blank:

Error message

Theme background field is blank: 

What it means

ThemeBackground.requireNonBlank throws this JsonParseException when a required source field is present but its value is empty or whitespace-only after trimming. Image.path, Paint.paint, and Builtin.id must be non-blank; a value like "" or " " is rejected just like a missing field.

Solutions

1. Provide the actual value for the field (a real path, paint string, or wallpaper id)
2. Remove the field and switch the type to "default" or "theme_color" if no concrete value applies
3. Trim or fill placeholder values in generated manifests before shipping them

Example fix

// before
{"type": "image", "path": ""}
// after
{"type": "image", "path": "assets/bg.png"}

if (obj.has("path") && obj.get("path").getAsString().isBlank()) throw new IllegalArgumentException("path must not be blank");

try { ThemeBackground.fromJson(obj); } catch (JsonParseException e) { LOG.warning("Blank background field: " + e.getMessage()); }

When it happens

Trigger: fromJson on {"type":"image","path":""}, {"type":"paint","paint":" "}, or {"type":"builtin","id":""} — any empty or all-whitespace string for the field required by that type.

Common situations: Templated or generated theme manifests where a placeholder value was never filled in, or an editor stripping a value while keeping the key.

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

• Theme background without type must contain only one source…
• Localized text cannot be empty object
• authlib-injectors.json -> urls cannot be null.
• Missing protected payload member: protection
• Invalid URL:

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemeBackground.java:132

    private static @Nullable String readString(JsonObject object, String field) {
        JsonElement element = object.get(field);
        if (element == null) {
            return null;
        }
        if (!(element instanceof JsonPrimitive primitive) || !primitive.isString()) {
            throw new JsonParseException("Theme background field must be a string: " + field);
        }
        return primitive.getAsString();
    }

    /// Returns a required non-blank string value.
    private static String requireNonBlank(@Nullable String value, String field) {
        if (value == null) {
            throw new JsonParseException("Theme background field is missing: " + field);
        }
        String trimmed = value.trim();
        if (trimmed.isEmpty()) {
            throw new JsonParseException("Theme background field is blank: " + field);
        }
        return trimmed;
    }

    /// A source that delegates to HMCL's launcher default background resolution.
    @NotNullByDefault
    record Default() implements ThemeBackground {
        /// Adds this source to a JSON object.
        @Override
        public void addToJsonObject(JsonObject object) {
            object.addProperty(FIELD_TYPE, "default");
        }

    }

    /// A source that uses a launcher built-in wallpaper.
    ///
    /// @param id the built-in wallpaper ID, or `null` for the fallback built-in wallpaper

View on GitHub (pinned to 24702dc5a0)