{"record":{"id":"e7ef3322c327713d","repo":"HMCL-dev/HMCL","slug":"theme-background-image-does-not-exist-source","errorCode":null,"errorMessage":"Theme background image does not exist: ${source}","messagePattern":"Theme background image does not exist: (.+?)","errorType":"validation","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java","lineNumber":1486,"sourceCode":"    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)) {\n            throw new IOException(\"Theme background URL must be HTTP or HTTPS: \" + url);\n        }\n","sourceCodeStart":1468,"sourceCodeEnd":1504,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java#L1468-L1504","documentation":"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.","triggerScenarios":"Exporting a theme pack whose background imagePath() resolves (after toAbsolutePath().normalize()) to a path where Files.isRegularFile(source) is false — typically a missing file.","commonSituations":"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.","solutions":["Restore the missing image at the configured path, or update the theme's imagePath to an existing file.","Verify the file exists with Files.isRegularFile(Path.of(path)) before exporting.","If the pack was moved between machines, use a path relative to the theme location or re-copy the asset."],"exampleFix":"// before\n\"background\": { \"imagePath\": \"/home/user/wallpapers/old.png\" } // deleted\n// after\n\"background\": { \"imagePath\": \"/home/user/wallpapers/current.png\" }","handlingStrategy":"validation","validationCode":"Path p = Path.of(configuredPath).toAbsolutePath().normalize();\nif (!Files.isRegularFile(p)) throw new IllegalArgumentException(\"background image does not exist: \" + p);","typeGuard":null,"tryCatchPattern":"try {\n    exportThemePack(...);\n} catch (IOException e) {\n    if (e.getMessage().startsWith(\"Theme background image does not exist\")) {\n        // prompt user to fix/restore the image path\n    }\n}","preventionTips":["Ship image assets together with the manifest and verify their presence before distribution.","Re-check paths after moving or renaming wallpaper files referenced by themes."],"tags":["theme-pack","filesystem","io","missing-file"],"backgroundTag":"file-not-found","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"}