{"record":{"id":"86803a019e0df491","repo":"HMCL-dev/HMCL","slug":"theme-background-field-is-blank","errorCode":null,"errorMessage":"Theme background field is blank: ","messagePattern":"Theme background field is blank: ","errorType":"validation","errorClass":"JsonParseException","httpStatus":null,"severity":"error","filePath":"HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemeBackground.java","lineNumber":132,"sourceCode":"    private static @Nullable String readString(JsonObject object, String field) {\n        JsonElement element = object.get(field);\n        if (element == null) {\n            return null;\n        }\n        if (!(element instanceof JsonPrimitive primitive) || !primitive.isString()) {\n            throw new JsonParseException(\"Theme background field must be a string: \" + field);\n        }\n        return primitive.getAsString();\n    }\n\n    /// Returns a required non-blank string value.\n    private static String requireNonBlank(@Nullable String value, String field) {\n        if (value == null) {\n            throw new JsonParseException(\"Theme background field is missing: \" + field);\n        }\n        String trimmed = value.trim();\n        if (trimmed.isEmpty()) {\n            throw new JsonParseException(\"Theme background field is blank: \" + field);\n        }\n        return trimmed;\n    }\n\n    /// A source that delegates to HMCL's launcher default background resolution.\n    @NotNullByDefault\n    record Default() implements ThemeBackground {\n        /// Adds this source to a JSON object.\n        @Override\n        public void addToJsonObject(JsonObject object) {\n            object.addProperty(FIELD_TYPE, \"default\");\n        }\n\n    }\n\n    /// A source that uses a launcher built-in wallpaper.\n    ///\n    /// @param id the built-in wallpaper ID, or `null` for the fallback built-in wallpaper","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemeBackground.java#L114-L150","documentation":"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.","triggerScenarios":"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.","commonSituations":"Templated or generated theme manifests where a placeholder value was never filled in, or an editor stripping a value while keeping the key.","solutions":["Provide the actual value for the field (a real path, paint string, or wallpaper id)","Remove the field and switch the type to \"default\" or \"theme_color\" if no concrete value applies","Trim or fill placeholder values in generated manifests before shipping them"],"exampleFix":"// before\n{\"type\": \"image\", \"path\": \"\"}\n// after\n{\"type\": \"image\", \"path\": \"assets/bg.png\"}","handlingStrategy":"validation","validationCode":"if (obj.has(\"path\") && obj.get(\"path\").getAsString().isBlank()) throw new IllegalArgumentException(\"path must not be blank\");","typeGuard":null,"tryCatchPattern":"try { ThemeBackground.fromJson(obj); } catch (JsonParseException e) { LOG.warning(\"Blank background field: \" + e.getMessage()); }","preventionTips":["Trim and reject empty values when generating manifests","Never leave placeholder values unfilled","Drop fields you cannot populate instead of writing empty strings"],"tags":["json","validation","empty-value","theme-config"],"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-15T23:17:13.987Z"}