What causes "Failed to load wallpaper image: ${imageFile}" in HMCL-dev/HMCL?

Check the cause chain of the IOException for the underlying decode error and repair or replace the image file.

HMCL-dev/HMCL · error · IOException

Failed to load wallpaper image

Error message

Failed to load wallpaper image: ${imageFile}

What it means

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.

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.

Example fix

// before
wallpaper: "bg.png" // actually a truncated HTML error page saved as .png
// after
wallpaper: "bg.png" // re-saved as a valid PNG

Defensive patterns

Strategy: try-catch

Validate before calling

boolean looksLikeImage = Files.probeContentType(imageFile) != null && Files.probeContentType(imageFile).startsWith("image/");

Try / catch

try { color = extractor.extract(imageFile, fallback); } catch (IOException e) { color = fallback; log.warn("wallpaper load failed", e.getCause()); }

Prevention

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

When it happens

Trigger: 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.

Common situations: Wallpaper file with a wrong extension (renamed .txt or truncated download); unsupported/corrupt image format JavaFX cannot decode; extremely large images exhausting memory.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/WallpaperColorExtractor.java:54

    /// Extracts a theme color from an image file.
    ///
    /// @param imageFile the image file
    /// @param fallback the fallback color used when extraction fails
    /// @return the extracted color, or `fallback` when no suitable color is found
    /// @throws IOException if the image file cannot be read
    public static ThemeColor extract(Path imageFile, ThemeColor fallback) throws IOException {
        Objects.requireNonNull(imageFile);
        Objects.requireNonNull(fallback);

        Image image;
        try {
            image = FXUtils.loadImage(imageFile);
        } catch (Exception e) {
            if (e instanceof IOException ioException) {
                throw ioException;
            }
            throw new IOException("Failed to load wallpaper image: " + imageFile, e);
        }

        return extract(image, fallback);
    }

    /// Extracts a theme color from a theme-pack resource.
    ///
    /// @param resource the theme-pack resource
    /// @param fallback the fallback color used when extraction fails
    /// @return the extracted color, or `fallback` when no suitable color is found
    /// @throws IOException if the resource cannot be read
    static ThemeColor extract(ThemePackResource resource, ThemeColor fallback) throws IOException {
        Objects.requireNonNull(resource);
        Objects.requireNonNull(fallback);

        Image image;
        try {
            image = FXUtils.loadImage(resource.openStream(), resource.name());

View on GitHub (pinned to 24702dc5a0)