{"record":{"id":"571a2ce5d38c91e3","repo":"HMCL-dev/HMCL","slug":"failed-to-load-wallpaper-image","errorCode":null,"errorMessage":"Failed to load wallpaper image: ","messagePattern":"Failed to load wallpaper image: ","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"HMCL/src/main/java/org/jackhuang/hmcl/theme/WallpaperColorExtractor.java","lineNumber":77,"sourceCode":"\n    /// Extracts a theme color from a theme-pack resource.\n    ///\n    /// @param resource the theme-pack resource\n    /// @param fallback the fallback color used when extraction fails\n    /// @return the extracted color, or `fallback` when no suitable color is found\n    /// @throws IOException if the resource cannot be read\n    static ThemeColor extract(ThemePackResource resource, ThemeColor fallback) throws IOException {\n        Objects.requireNonNull(resource);\n        Objects.requireNonNull(fallback);\n\n        Image image;\n        try {\n            image = FXUtils.loadImage(resource.openStream(), resource.name());\n        } catch (Exception e) {\n            if (e instanceof IOException ioException) {\n                throw ioException;\n            }\n            throw new IOException(\"Failed to load wallpaper image: \" + resource.name(), e);\n        }\n\n        return extract(image, fallback);\n    }\n\n    /// Extracts a theme color from a loaded image.\n    ///\n    /// @param image the loaded image\n    /// @param fallback the fallback color used when extraction fails\n    /// @return the extracted color, or `fallback` when no suitable color is found\n    public static ThemeColor extract(Image image, ThemeColor fallback) {\n        Objects.requireNonNull(image);\n        Objects.requireNonNull(fallback);\n\n        Color extracted = ColorScheme.extractColor(image, fallback.color());\n        return ThemeColor.of(extracted);\n    }\n}","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCL/src/main/java/org/jackhuang/hmcl/theme/WallpaperColorExtractor.java#L59-L95","documentation":"Thrown by WallpaperColorExtractor.extract(ResourceNotFoundException-style resource wrapper) when FXUtils.loadImage fails to decode a wallpaper image from the resource stream with an exception that is not an IOException (e.g. image decoding/JavaFX errors). The original resource name is wrapped so the caller knows which wallpaper failed.","triggerScenarios":"Calling WallpaperColorExtractor.extract with a wallpaper resource whose stream cannot be decoded by FXUtils.loadImage — corrupt/unsupported image bytes, JavaFX Image decoding exceptions (non-IOException), e.g. a broken or mis-typed image file set as theme wallpaper.","commonSituations":"Users selecting a custom wallpaper file that is corrupt, truncated, or in an unsupported format; bundled wallpaper resources damaged or mispackaged in the distribution; environment issues where the JavaFX image loaders are unavailable.","solutions":["Verify the wallpaper file is a valid, decodable PNG/JPG and re-save/export it with an image tool","Check that the resource path/name points to an actually bundled image (resource.openStream() succeeded, decoding failed)","Catch IOException at the call site and fall back to a default wallpaper / fallback theme color","Reinstall or repack HMCL if a bundled wallpaper resource is corrupt"],"exampleFix":"// before\nThemeColor color = wallpaperColorExtractor.extract(resource, fallback);\n// after\nThemeColor color;\ntry {\n    color = wallpaperColorExtractor.extract(resource, fallback);\n} catch (IOException e) {\n    LOG.warning(\"Wallpaper failed to load, using fallback color\", e);\n    color = fallback;\n}","handlingStrategy":"try-catch","validationCode":"Path p = Paths.get(\"wallpaper.png\");\nif (!Files.isRegularFile(p) || Files.size(p) == 0) { /* use default wallpaper */ }\ntry (var in = Files.newInputStream(p)) { new javafx.scene.image.Image(in).getWidth(); } // probe decodability","typeGuard":"static boolean isDecodableImage(java.io.InputStream in) {\n    Image img = new Image(in, 0, 0, true, true, true);\n    return !img.isError();\n}","tryCatchPattern":"try {\n    color = extractor.extract(resource, fallback);\n} catch (IOException e) {\n    LOG.warning(\"Wallpaper load failed: \" + e.getMessage(), e);\n    color = fallback;\n}","preventionTips":["Always pass a decodable PNG/JPG as wallpaper resource","Probe-decode the image once at startup and cache the result","Keep a bundled default wallpaper as fallback","Re-verify bundled resources after packaging"],"tags":["javafx","image-decoding","io"],"backgroundTag":"file-read-failed","analyzedSha":"24702dc5a0214034f4c27166d5fd30cad08cec19","analyzedAt":"2026-09-10T12:36:46.680Z","contentChangedAt":"2026-09-10T12:36:46.680Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}