{"record":{"id":"b978d54a0a9d463b","repo":"HMCL-dev/HMCL","slug":"cannot-find-suitable-encoding-for-the-zip","errorCode":null,"errorMessage":"Cannot find suitable encoding for the zip.","messagePattern":"Cannot find suitable encoding for the zip\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"HMCLCore/src/main/java/org/jackhuang/hmcl/util/io/CompressingUtils.java","lineNumber":128,"sourceCode":"                \"ISO-8859-1\",\n                \"ISO-8859-5\",\n                \"ISO-8859-7\",\n                \"ISO-8859-8\",\n                \"UTF-16LE\", \"UTF-16BE\",\n                \"UTF-32LE\", \"UTF-32BE\"\n        };\n\n        for (String candidate : candidates) {\n            try {\n                Charset charset = Charset.forName(candidate);\n                if (!charset.equals(OperatingSystem.NATIVE_CHARSET) && testEncoding(zipFile, charset)) {\n                    return charset;\n                }\n            } catch (IllegalArgumentException ignored) {\n            }\n        }\n\n        throw new IOException(\"Cannot find suitable encoding for the zip.\");\n    }\n\n    public static ZipFileTree openZipTree(Path zipFile) throws IOException {\n        return new ZipFileTree(openZipFile(zipFile));\n    }\n\n    public static ZipArchiveReader openZipFile(Path zipFile) throws IOException {\n        return openZipFileWithPossibleEncoding(zipFile, StandardCharsets.UTF_8);\n    }\n\n    public static ZipArchiveReader openZipFile(Path zipFile, Charset charset) throws IOException {\n        return new ZipArchiveReader(zipFile, charset, true, true);\n    }\n\n    public static ZipArchiveReader openZipFileWithPossibleEncoding(Path zipFile, Charset possibleEncoding) throws IOException {\n        if (possibleEncoding == null)\n            possibleEncoding = StandardCharsets.UTF_8;\n","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/util/io/CompressingUtils.java#L110-L146","documentation":"CompressingUtils.findSuitableEncoding probes a list of candidate charsets (e.g. UTF-8, GBK) by trying to open the zip with each; when none can open the archive without IllegalArgumentException, it gives up and throws an IOException stating no suitable encoding exists.","triggerScenarios":"Calling findSuitableEncoding (directly or via openZipFile) on a file that is not a readable zip, or whose entry names cannot be decoded by any of the probed charsets, exhausting all candidates.","commonSituations":"The path points to a corrupted or truncated archive, or to a non-zip file renamed to .zip; legacy archives with exotic filename encodings not covered by the candidate list.","solutions":["Verify the file is a valid zip (e.g. open with a standard ZipFile or run a zip test utility).","Re-download or re-export the archive if it is corrupted.","If you control the code, extend the candidate charset list or use ZipFile with an explicit charset/UTF-8 flag."],"exampleFix":"// before\nCharset cs = CompressingUtils.findSuitableEncoding(path); // IOException on junk file\n\n// after\nif (!Files.isRegularFile(path) || !isZipSignature(path)) {\n    throw new IOException(\"Not a zip file: \" + path);\n}\nCharset cs = CompressingUtils.findSuitableEncoding(path);","handlingStrategy":"try-catch","validationCode":"byte[] sig = new byte[4];\ntry (InputStream in = Files.newInputStream(zipFile)) { if (in.read(sig) != 4 || sig[0] != 'P' || sig[1] != 'K') throw new IOException(\"Not a zip: \" + zipFile); }","typeGuard":null,"tryCatchPattern":"try { Charset cs = CompressingUtils.findSuitableEncoding(zipFile); } catch (IOException e) { log.error(\"Cannot decode zip with known charsets\", e); throw new UnrecoverableFormatException(zipFile, e); }","preventionTips":["Check the PK zip signature before processing archives.","Verify downloads against checksums.","Keep archives in well-supported encodings (UTF-8 flagged zips)."],"tags":["zip","encoding","charset","io"],"backgroundTag":"file-read-failed","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"}