{"record":{"id":"031bccba040d29ee","repo":"HMCL-dev/HMCL","slug":"theme-background-image-path-is-not-configured","errorCode":null,"errorMessage":"Theme background image path is not configured","messagePattern":"Theme background image path is not configured","errorType":"validation","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java","lineNumber":1479,"sourceCode":"            case THEME_COLOR -> new ThemeBackgroundSettings(\n                    new ThemeBackground.ThemeColor(),\n                    opacity);\n        };\n    }\n\n    /// Creates the image background source for the resolved current background image.\n    private static ThemeBackground.Image createCurrentImageBackgroundSource(\n            List<ThemePackAsset> assets,\n            ResolvedBackground background) throws IOException {\n        @Nullable ThemePackResource imageResource = background.imageResource();\n        if (imageResource != null) {\n            assets.add(new ThemePackAsset(imageResource, imageResource.name()));\n            return new ThemeBackground.Image(imageResource.name());\n        }\n\n        @Nullable Path imagePath = background.imagePath();\n        if (imagePath == null) {\n            throw new IOException(\"Theme background image path is not configured\");\n        }\n        Path source = imagePath.toAbsolutePath().normalize();\n        if (Files.isDirectory(source)) {\n            throw new IOException(\"Cannot export a background directory as a theme-pack asset: \" + source);\n        }\n        if (!Files.isRegularFile(source)) {\n            throw new IOException(\"Theme background image does not exist: \" + source);\n        }\n\n        String entryName = \"assets/wallpapers/\" + sanitizePathSegment(source.getFileName().toString());\n        assets.add(new ThemePackAsset(source, entryName));\n        return new ThemeBackground.Image(entryName);\n    }\n\n    /// Downloads the current network background and exports it as a theme-pack image asset.\n    private static ThemeBackground.Image createCurrentNetworkBackgroundSource(\n            List<ThemePackAsset> assets,\n            List<Path> temporaryFiles,","sourceCodeStart":1461,"sourceCodeEnd":1497,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java#L1461-L1497","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Set a concrete background image (with its imagePath) before exporting, e.g. via theme.setBackgroundImage(path).","Check background.imagePath() != null before invoking the export API and prompt the user to choose an image otherwise.","Skip background export or substitute a default image when the background has no path."],"exampleFix":"// before\nexporter.export(theme); // background may have null imagePath\n// after\nif (theme.getBackground().imagePath() == null) {\n    throw new IllegalStateException(\"Choose a background image before exporting\");\n}\nexporter.export(theme);","handlingStrategy":"try-catch","validationCode":"if (theme.getBackground().imagePath() == null) {\n    throw new IllegalStateException(\"Background image path must be configured before export\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    exporter.export(theme);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"image path is not configured\")) {\n      ui.promptChooseBackgroundImage();\n    } else throw e;\n}","preventionTips":["Require a user-selected background image before enabling export.","Check imagePath() != null in UI enablement logic.","Persist the background path in settings so exports always have one."],"tags":["theme-pack","export","missing-config"],"backgroundTag":"missing-required-config-field","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"}