{"record":{"id":"13b56b3e8d96e109","repo":"HMCL-dev/HMCL","slug":"theme-packs-cannot-reference-built-in-wallpaper","errorCode":null,"errorMessage":"Theme packs cannot reference built-in wallpaper: ${normalizedId}","messagePattern":"Theme packs cannot reference built-in wallpaper: (.+?)","errorType":"validation","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java","lineNumber":1594,"sourceCode":"        return SettingsManager.settings().getThemeAppearanceOverrides().contains(LauncherSettings.THEME_APPEARANCE_BACKGROUND_OPACITY)\n                ? currentBackgroundOpacity()\n                : 1.0;\n    }\n\n    /// Returns the currently selected built-in wallpaper ID.\n    private static String currentBuiltinBackgroundId() {\n        return BuiltinBackground.fromIdOrFallback(settings().builtinBackgroundIdProperty().get()).id();\n    }\n\n    /// Resolves a theme-pack built-in wallpaper ID.\n    private static String resolveBuiltinBackgroundId(@Nullable String id) throws IOException {\n        String normalizedId = StringUtils.isBlank(id)\n                ? BuiltinBackground.FALLBACK.id()\n                : id.trim().toLowerCase(Locale.ROOT);\n        if (BuiltinBackground.fromId(normalizedId) != null) {\n            return normalizedId;\n        }\n        throw new IOException(\"Theme packs cannot reference built-in wallpaper: \" + normalizedId);\n    }\n\n    /// Parses a serialized JavaFX paint value.\n    private static Paint parsePaint(String value) throws IOException {\n        try {\n            return Paint.valueOf(value);\n        } catch (IllegalArgumentException e) {\n            throw new IOException(\"Invalid theme background paint: \" + value, e);\n        }\n    }\n\n    /// Returns a non-blank string value.\n    private static String requireNonBlank(@Nullable String value, String name) throws IOException {\n        if (StringUtils.isBlank(value)) {\n            throw new IOException(\"Theme pack value is missing: \" + name);\n        }\n        return value.trim();\n    }","sourceCodeStart":1576,"sourceCodeEnd":1612,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java#L1576-L1612","documentation":"Thrown when parsing a theme-pack manifest whose background id resolves to a built-in wallpaper identifier. Built-in backgrounds are launcher-internal, so theme packs must not reference them; only custom ids declared by the pack itself are allowed.","triggerScenarios":"Reading a theme-pack manifest where the background id (after trim().toLowerCase(Locale.ROOT), or FALLBACK when blank) matches a known BuiltinBackground id, so BuiltinBackground.fromId(normalizedId) != null.","commonSituations":"Manifest author writes \"id\": \"default\" or another built-in wallpaper name thinking it selects the launcher default; copying background config from an ordinary theme settings file into a pack manifest; blank id normalizing to the built-in fallback id.","solutions":["Rename the background id in the manifest to a custom, non-built-in identifier unique to the pack.","Remove the built-in background reference and declare an image/paint background instead.","Check BuiltinBackground ids (e.g. the fallback id) and avoid any of them as theme-pack background ids."],"exampleFix":"// before\n{ \"background\": { \"type\": \"builtin\", \"id\": \"default\" } }\n// after\n{ \"background\": { \"type\": \"image\", \"id\": \"my-pack-wallpaper\", \"path\": \"assets/wallpapers/wall.png\" } }","handlingStrategy":"validation","validationCode":"String normalized = (id == null || id.isBlank()) ? \"fallback\" : id.trim().toLowerCase(Locale.ROOT);\nif (BuiltinBackground.fromId(normalized) != null) {\n    throw new IllegalArgumentException(\"use a custom background id, not a built-in one: \" + normalized);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefix custom background ids with the pack name to avoid collisions with built-in ids.","Never leave a theme-pack background id blank; blank normalizes to the built-in fallback id."],"tags":["theme-pack","manifest","validation","identifier"],"backgroundTag":"invalid-identifier","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"}