HMCL-dev/HMCL · error · IOException

Theme background image does not exist

Error message

Theme background image does not exist: ${source}

What it means

Thrown by ThemePackManager when the background image path is not a regular file at export time. After ruling out directories (error 120), this check catches paths that do not exist or are special files, since the asset cannot be read and added to the pack's ZIP entries.

Solutions

  1. Restore the missing image at the configured path, or update the theme's imagePath to an existing file.
  2. Verify the file exists with Files.isRegularFile(Path.of(path)) before exporting.
  3. If the pack was moved between machines, use a path relative to the theme location or re-copy the asset.

Example fix

// before
"background": { "imagePath": "/home/user/wallpapers/old.png" } // deleted
// after
"background": { "imagePath": "/home/user/wallpapers/current.png" }
Defensive patterns

Strategy: validation

Validate before calling

Path p = Path.of(configuredPath).toAbsolutePath().normalize();
if (!Files.isRegularFile(p)) throw new IllegalArgumentException("background image does not exist: " + p);

Try / catch

try {
    exportThemePack(...);
} catch (IOException e) {
    if (e.getMessage().startsWith("Theme background image does not exist")) {
        // prompt user to fix/restore the image path
    }
}

Prevention

When it happens

Trigger: Exporting a theme pack whose background imagePath() resolves (after toAbsolutePath().normalize()) to a path where Files.isRegularFile(source) is false — typically a missing file.

Common situations: The wallpaper file was deleted or renamed after the theme referenced it; the theme manifest contains a typo in the path; the pack was authored on another machine with different absolute paths; a portable install moved and lost relative assets.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java:1486

    private static ThemeBackground.Image createCurrentImageBackgroundSource(
            List<ThemePackAsset> assets,
            ResolvedBackground background) throws IOException {
        @Nullable ThemePackResource imageResource = background.imageResource();
        if (imageResource != null) {
            assets.add(new ThemePackAsset(imageResource, imageResource.name()));
            return new ThemeBackground.Image(imageResource.name());
        }

        @Nullable Path imagePath = background.imagePath();
        if (imagePath == null) {
            throw new IOException("Theme background image path is not configured");
        }
        Path source = imagePath.toAbsolutePath().normalize();
        if (Files.isDirectory(source)) {
            throw new IOException("Cannot export a background directory as a theme-pack asset: " + source);
        }
        if (!Files.isRegularFile(source)) {
            throw new IOException("Theme background image does not exist: " + source);
        }

        String entryName = "assets/wallpapers/" + sanitizePathSegment(source.getFileName().toString());
        assets.add(new ThemePackAsset(source, entryName));
        return new ThemeBackground.Image(entryName);
    }

    /// Downloads the current network background and exports it as a theme-pack image asset.
    private static ThemeBackground.Image createCurrentNetworkBackgroundSource(
            List<ThemePackAsset> assets,
            List<Path> temporaryFiles,
            ResolvedBackground background) throws IOException {
        String url = requireNonBlank(background.networkImageUrl(), "background.url");
        URI uri = NetworkUtils.toURI(url);
        if (!NetworkUtils.isHttpUri(uri)) {
            throw new IOException("Theme background URL must be HTTP or HTTPS: " + url);
        }

View on GitHub (pinned to 24702dc5a0)