{"record":{"id":"bf959c89339774e3","repo":"HMCL-dev/HMCL","slug":"failed-to-load-wallpaper-image-imagefile","errorCode":null,"errorMessage":"Failed to load wallpaper image: ${imageFile}","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":54,"sourceCode":"\n    /// Extracts a theme color from an image file.\n    ///\n    /// @param imageFile the image file\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 image file cannot be read\n    public static ThemeColor extract(Path imageFile, ThemeColor fallback) throws IOException {\n        Objects.requireNonNull(imageFile);\n        Objects.requireNonNull(fallback);\n\n        Image image;\n        try {\n            image = FXUtils.loadImage(imageFile);\n        } catch (Exception e) {\n            if (e instanceof IOException ioException) {\n                throw ioException;\n            }\n            throw new IOException(\"Failed to load wallpaper image: \" + imageFile, e);\n        }\n\n        return extract(image, fallback);\n    }\n\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());","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCL/src/main/java/org/jackhuang/hmcl/theme/WallpaperColorExtractor.java#L36-L72","documentation":"WallpaperColorExtractor.extract(Path, fallback) loads the wallpaper via FXUtils.loadImage; any failure that is not already an IOException is wrapped into IOException \"Failed to load wallpaper image: <imageFile>\" with the original cause attached. IOExceptions (e.g. file-not-found) are rethrown unchanged, so this error specifically covers decode/format failures of an existing image file.","triggerScenarios":"loadImage throws a non-IOException (e.g. MediaException/Image decoding error, OutOfMemoryError for huge images, NullPointerException on corrupt input) when reading the wallpaper file; extract(image, fallback) is then not reached.","commonSituations":"Wallpaper file with a wrong extension (renamed .txt or truncated download); unsupported/corrupt image format JavaFX cannot decode; extremely large images exhausting memory.","solutions":["Check the cause chain of the IOException for the underlying decode error and repair or replace the image file.","Re-export the wallpaper as a standard PNG/JPEG and repack the theme.","Verify the file at imageFile is actually an image and fully downloaded; then retry."],"exampleFix":"// before\nwallpaper: \"bg.png\" // actually a truncated HTML error page saved as .png\n// after\nwallpaper: \"bg.png\" // re-saved as a valid PNG","handlingStrategy":"try-catch","validationCode":"boolean looksLikeImage = Files.probeContentType(imageFile) != null && Files.probeContentType(imageFile).startsWith(\"image/\");","typeGuard":null,"tryCatchPattern":"try { color = extractor.extract(imageFile, fallback); } catch (IOException e) { color = fallback; log.warn(\"wallpaper load failed\", e.getCause()); }","preventionTips":["Validate wallpaper files are real PNG/JPEG images before packaging","Downscale very large images to avoid decode memory failures","Always inspect getCause() to find the true decode error"],"tags":["theme-pack","image","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-15T23:17:13.987Z"}