{"record":{"id":"f01e7260a4d373dc","repo":"HMCL-dev/HMCL","slug":"built-in-theme-pack-asset-is-missing-entryname","errorCode":null,"errorMessage":"Built-in theme-pack asset is missing: ${entryName}","messagePattern":"Built-in theme-pack asset is missing: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java","lineNumber":1241,"sourceCode":"        try (ZipArchiveReader zipFile = new ZipArchiveReader(installedFile, StandardCharsets.UTF_8)) {\n            ZipArchiveEntry entry = zipFile.getEntry(normalizedEntryName);\n            if (entry == null || entry.isDirectory()) {\n                throw new IOException(\"Installed theme-pack asset is missing: \" + normalizedEntryName);\n            }\n        }\n        return new ThemePackResource.Zip(installedFile, normalizedEntryName);\n    }\n\n    /// Resolves one asset stored in a bundled theme pack.\n    private static ThemePackResource resolveBuiltinAsset(ThemePackLocation.Builtin builtin, String entryName) throws IOException {\n        String id = ThemePackManifest.requirePackageId(builtin.id());\n        String resourcePath = \"/assets/themes/\" + id + \"/\" + entryName;\n        try (InputStream input = ThemePackManager.class.getResourceAsStream(resourcePath)) {\n            if (input != null) {\n                return new ThemePackResource.Builtin(resourcePath, entryName);\n            }\n        }\n        throw new IOException(\"Built-in theme-pack asset is missing: \" + entryName);\n    }\n\n    /// Returns the installed theme-pack file under a theme-pack directory for one package ID.\n    private static Path installedThemePackFile(Path themePacksDirectory, String packId) {\n        String id = ThemePackManifest.requirePackageId(packId);\n        return themePacksDirectory\n                .resolve(id + ThemePackExporter.FILE_EXTENSION)\n                .toAbsolutePath()\n                .normalize();\n    }\n\n    /// Returns whether a path is an installed theme-pack file candidate.\n    private static boolean isInstalledThemePackFile(Path path) {\n        String fileName = path.getFileName().toString();\n        return !fileName.startsWith(\".\")\n                && fileName.endsWith(ThemePackExporter.FILE_EXTENSION);\n    }\n","sourceCodeStart":1223,"sourceCodeEnd":1259,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java#L1223-L1259","documentation":"ThemePackManager resolves built-in theme-pack assets from the classpath at /assets/themes/<id>/<entryName>. This IOException is thrown when that classpath resource does not exist, meaning the packaged jar is missing the expected bundled asset. It signals a build/packaging defect rather than a user problem, since built-in assets ship with the library.","triggerScenarios":"Calling the public built-in asset resolver (ThemePackManager, public API) with a theme-pack id + entryName whose path /assets/themes/<id>/<entryName> has no classpath resource; input from getResourceAsStream is null.","commonSituations":"Running against a partially built or shaded jar where assets were excluded by build filters; referencing a theme id or entry that was removed/renamed in a newer version; custom classloaders that do not expose the jar's resources.","solutions":["Verify /assets/themes/<id>/<entryName> exists in the jar on the classpath (unzip -l hmcl.jar | grep assets/themes).","Rebuild the project so theme resources are copied into the jar; check build config resource excludes.","Confirm the theme id and entryName are valid for this library version (names may have changed between versions).","If using a custom classloader, ensure it can load resources from the HMCL jar."],"exampleFix":"// before\nThemePackResource res = ThemePackManager.resolveBuiltinAsset(\"legacy\", \"theme.css\");\n// after\nif (ThemePackManager.builtinAssetExists(\"modern\", \"theme.css\")) {\n    ThemePackResource res = ThemePackManager.resolveBuiltinAsset(\"modern\", \"theme.css\");\n} else {\n    ThemePackResource res = ThemePackManager.resolveDefaultAsset();\n}","handlingStrategy":"fallback","validationCode":"boolean ok = ThemePackManager.class.getResourceAsStream(\"/assets/themes/\" + id + \"/\" + entryName) != null;\nif (!ok) useDefaultThemePack();","typeGuard":null,"tryCatchPattern":"try {\n    resource = ThemePackManager.resolveBuiltinAsset(id, entryName);\n} catch (IOException e) {\n    LOG.warn(\"builtin theme asset missing: {}\", e.getMessage());\n    resource = ThemePackManager.resolveDefaultAsset();\n}","preventionTips":["Check build resource filters after any build-config change.","List the jar contents in CI to assert required theme assets exist.","Avoid hardcoding theme ids/entries; enumerate them from a registry."],"tags":["classpath","missing-resource","theme-pack"],"backgroundTag":"resource-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"}