HMCL-dev/HMCL · error · JsonParseException

Unsupported theme background type:

Error message

Unsupported theme background type: 

What it means

ThemeBackground.fromJson throws this when the "type" field contains a value that does not match any supported enum literal after normalization: trim, replace '-' with '_', uppercase. Supported values are DEFAULT, BUILTIN, IMAGE, PAINT, and THEME_COLOR. The exception is a Gson JsonParseException whose message appends the offending type string.

Solutions

1. Change "type" to one of the supported values: default, builtin, image, paint, theme_color
2. Check for spelling/whitespace issues; keep the value lowercase for safety
3. Verify the HMCL version supports the desired type; if the type is from a newer release, upgrade HMCL or use a supported alternative

Example fix

// before
{"type": "gradient"}
// after
{"type": "paint", "paint": "linear-gradient(to bottom right, #123, #456)"}

String t = obj.has("type") ? obj.get("type").getAsString() : null;
if (t != null && Set.of("default","builtin","image","paint","theme_color").stream().noneMatch(v -> v.equalsIgnoreCase(t.replace('-', '_')))) throw new IllegalArgumentException("Unsupported type: " + t);

try { ThemeBackground.fromJson(obj); } catch (JsonParseException e) { LOG.warning("Unknown background type, using default: " + e.getMessage()); return new ThemeBackground.Default(); }

When it happens

Trigger: fromJson on a JsonObject whose "type" is not one of default/builtin/image/paint/theme_color (case-insensitive, hyphen or underscore), e.g. {"type":"video"} or {"type":"imagefile"}.

Common situations: Typo in a theme-pack manifest ("imag" instead of "image"), a type added by a newer/older HMCL version than the parser, or authors copying type names from other launchers' theme formats.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid theme color:
• Unsupported protected payload:
• Theme background without type must contain only one source…
• Theme background field must be a string:
• Theme background field is missing:

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

Appendix: source

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

            if (id != null) {
                return new Builtin(id);
            }
            if (path != null) {
                return new Image(path);
            }
            if (paint != null) {
                return new Paint(paint);
            }
            return null;
        }

        return switch (type.trim().replace('-', '_').toUpperCase(Locale.ROOT)) {
            case "DEFAULT" -> new Default();
            case "BUILTIN" -> new Builtin(id);
            case "IMAGE" -> new Image(path);
            case "PAINT" -> new Paint(paint);
            case "THEME_COLOR" -> new ThemeColor();
            default -> throw new JsonParseException("Unsupported theme background type: " + type);
        };
    }

    /// Reads an optional string field.
    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) {

View on GitHub (pinned to 24702dc5a0)