{"record":{"id":"2ec60db487880cfe","repo":"HMCL-dev/HMCL","slug":"cannot-export-a-background-directory-as-a-theme-pa","errorCode":null,"errorMessage":"Cannot export a background directory as a theme-pack asset: ${source}","messagePattern":"Cannot export a background directory as a theme-pack asset: (.+?)","errorType":"validation","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java","lineNumber":1483,"sourceCode":"    }\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,\n            ResolvedBackground background) throws IOException {\n        String url = requireNonBlank(background.networkImageUrl(), \"background.url\");\n        URI uri = NetworkUtils.toURI(url);\n        if (!NetworkUtils.isHttpUri(uri)) {","sourceCodeStart":1465,"sourceCodeEnd":1501,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java#L1465-L1501","documentation":"Thrown by ThemePackManager when exporting a theme pack whose background resolves to a directory rather than an image file. Theme packs bundle backgrounds as ZIP entries under assets/wallpapers/, and a directory cannot be stored as a single asset. The manager fails fast before building the pack.","triggerScenarios":"Calling the theme-pack export flow with a background whose imagePath() points at a directory (Files.isDirectory(source) is true after toAbsolutePath().normalize()).","commonSituations":"A theme JSON/manifest configured with a background path that accidentally points at a folder (e.g. an extracted wallpaper directory instead of the wallpaper file inside it); a misconfigured custom-background setting where the user selected a directory; a symlink resolving to a directory.","solutions":["Change the theme's background image path to point at the actual image file inside the directory (e.g. dir/wallpaper.png instead of dir).","If the directory contains the intended image, list its contents and pick a regular file; verify with Files.isRegularFile before exporting.","Fix any symlink or path-join mistake that makes imagePath resolve to a directory instead of a file."],"exampleFix":"// before\n\"background\": { \"imagePath\": \"/home/user/wallpapers/\" }\n// after\n\"background\": { \"imagePath\": \"/home/user/wallpapers/sunset.png\" }","handlingStrategy":"validation","validationCode":"Path p = Path.of(configuredPath).toAbsolutePath().normalize();\nif (Files.isDirectory(p)) throw new IllegalArgumentException(\"background must be an image file, not a directory: \" + p);\nif (!Files.isRegularFile(p)) throw new IllegalArgumentException(\"background image missing: \" + p);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Point background imagePath at files, never directories, when authoring theme manifests.","Run Files.isRegularFile checks on all asset paths before export."],"tags":["theme-pack","filesystem","io","validation"],"backgroundTag":"incompatible-source-type","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"}