{"record":{"id":"b573f564a9029fec","repo":"HMCL-dev/HMCL","slug":"unsupported-theme-pack-entry-entryname","errorCode":null,"errorMessage":"Unsupported theme-pack entry: ${entryName}","messagePattern":"Unsupported theme-pack entry: (.+?)","errorType":"validation","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java","lineNumber":1428,"sourceCode":"            if (segment.isEmpty() || \".\".equals(segment) || \"..\".equals(segment)) {\n                throw new IOException(\"Theme-pack entry contains an unsafe segment: \" + entryName);\n            }\n            for (int i = 0; i < segment.length(); i++) {\n                char ch = segment.charAt(i);\n                if (Character.isISOControl(ch) || ch == '\\0') {\n                    throw new IOException(\"Theme-pack entry contains a control character: \" + entryName);\n                }\n            }\n        }\n        return normalized;\n    }\n\n    /// Checks that a theme-pack zip entry belongs to the current file layout.\n    private static void checkSupportedThemePackEntry(String entryName) throws IOException {\n        if (!ThemePackExporter.MANIFEST_ENTRY.equals(entryName)\n                && !\"assets\".equals(entryName)\n                && !entryName.startsWith(\"assets/\")) {\n            throw new IOException(\"Unsupported theme-pack entry: \" + entryName);\n        }\n    }\n\n    /// Deletes an existing file, symbolic link, or directory tree.\n    private static void deleteIfExists(Path path) throws IOException {\n        if (Files.exists(path) || Files.isSymbolicLink(path)) {\n            FileUtils.forceDelete(path);\n        }\n    }\n\n    /// Creates the background model for the current launcher settings.\n    private static ThemeBackgroundSettings createCurrentBackground(\n            List<ThemePackAsset> assets,\n            List<Path> temporaryFiles) throws IOException {\n        ResolvedBackground background = resolveCurrentBackground(currentResolveContext());\n        Double opacity = background.opacity();\n        return switch (background.type()) {\n            case DEFAULT -> new ThemeBackgroundSettings(","sourceCodeStart":1410,"sourceCodeEnd":1446,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java#L1410-L1446","documentation":"Theme packs allow only the manifest entry and asset entries under 'assets/'. Any other entry name causes checkSupportedThemePackEntry to throw this IOException, enforcing the pack's file layout and preventing unexpected files from being extracted.","triggerScenarios":"Installing a zip containing stray files at the root (README.md, .DS_Store, __MACOSX/,Thumbs.db, license.txt) or assets stored outside the assets/ directory (e.g. 'images/bg.png').","commonSituations":"macOS Finder zips adding __MACOSX/ and .DS_Store entries; hand-built packs with a top-level 'images' or 'skins' folder; old/experimental layouts from other versions.","solutions":["Repack the zip with only theme-pack.json and an assets/ directory at the root.","Move all media files under assets/ inside the archive.","Exclude OS metadata (e.g. `zip -x '__MACOSX*' '*.DS_Store'`) when creating the archive.","Use ThemePackExporter so only supported entries are written."],"exampleFix":"// before\nzip -r pack.zip theme-pack.json assets images/ README.md\n// after\nzip -r pack.zip theme-pack.json assets -x '*.DS_Store' '__MACOSX*'","handlingStrategy":"validation","validationCode":"for (var e : Collections.list(new ZipFile(pack).entries())) {\n    String n = e.getName();\n    if (!n.equals(\"theme-pack.json\") && !n.equals(\"assets\") && !n.startsWith(\"assets/\")) throw new IllegalArgumentException(\"unsupported entry: \" + n);\n}","typeGuard":null,"tryCatchPattern":"try {\n    ThemePackManager.install(pack, dir);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"Unsupported theme-pack entry\")) {\n      ui.show(\"Pack contains unsupported files; remove them or re-export via the exporter.\");\n    } else throw e;\n}","preventionTips":["Keep packs to exactly theme-pack.json + assets/.","Exclude __MACOSX, .DS_Store, Thumbs.db when zipping.","Put all media under assets/."],"tags":["zip","theme-pack","layout-validation"],"backgroundTag":"unsupported-operation","analyzedSha":"24702dc5a0214034f4c27166d5fd30cad08cec19","analyzedAt":"2026-09-10T12:36:46.680Z","contentChangedAt":"2026-09-10T12:36:46.680Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}