HMCL-dev/HMCL · error · IOException

Theme background image path is not configured

Error message

Theme background image path is not configured

What it means

While exporting a theme pack, the exporter converts the current theme background into an asset. A Image background always has a name, but if background.imagePath() returns null — the background is not backed by a configured file path — this IOException is thrown because there is no file to package as an asset.

Solutions

  1. Set a concrete background image (with its imagePath) before exporting, e.g. via theme.setBackgroundImage(path).
  2. Check background.imagePath() != null before invoking the export API and prompt the user to choose an image otherwise.
  3. Skip background export or substitute a default image when the background has no path.

Example fix

// before
exporter.export(theme); // background may have null imagePath
// after
if (theme.getBackground().imagePath() == null) {
    throw new IllegalStateException("Choose a background image before exporting");
}
exporter.export(theme);
Defensive patterns

Strategy: try-catch

Validate before calling

if (theme.getBackground().imagePath() == null) {
    throw new IllegalStateException("Background image path must be configured before export");
}

Try / catch

try {
    exporter.export(theme);
} catch (IOException e) {
    if (e.getMessage().contains("image path is not configured")) {
      ui.promptChooseBackgroundImage();
    } else throw e;
}

Prevention

When it happens

Trigger: Calling the theme-pack export API while the current background is an Image whose imagePath was never set (e.g. a built-in/default image background or one constructed programmatically without a path).

Common situations: Exporting a pack before the user picks a background image; a background loaded from a preset that stores no path; configuration where the image path setting was cleared but the background object remained.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

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

            case THEME_COLOR -> new ThemeBackgroundSettings(
                    new ThemeBackground.ThemeColor(),
                    opacity);
        };
    }

    /// Creates the image background source for the resolved current background image.
    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,

View on GitHub (pinned to 24702dc5a0)