HMCL-dev/HMCL · error

Cannot find suitable encoding for the zip.

Error message

Cannot find suitable encoding for the zip.

What it means

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.

Solutions

  1. Verify the file is a valid zip (e.g. open with a standard ZipFile or run a zip test utility).
  2. Re-download or re-export the archive if it is corrupted.
  3. If you control the code, extend the candidate charset list or use ZipFile with an explicit charset/UTF-8 flag.

Example fix

// before
Charset cs = CompressingUtils.findSuitableEncoding(path); // IOException on junk file

// after
if (!Files.isRegularFile(path) || !isZipSignature(path)) {
    throw new IOException("Not a zip file: " + path);
}
Charset cs = CompressingUtils.findSuitableEncoding(path);
Defensive patterns

Strategy: try-catch

Validate before calling

byte[] sig = new byte[4];
try (InputStream in = Files.newInputStream(zipFile)) { if (in.read(sig) != 4 || sig[0] != 'P' || sig[1] != 'K') throw new IOException("Not a zip: " + zipFile); }

Try / catch

try { Charset cs = CompressingUtils.findSuitableEncoding(zipFile); } catch (IOException e) { log.error("Cannot decode zip with known charsets", e); throw new UnrecoverableFormatException(zipFile, e); }

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

AI-assisted analysis of HMCL-dev/HMCL@24702dc5a0 (2026-09-10). Data as JSON: /api/errors/b978d54a0a9d463b. Report an issue: GitHub.

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/util/io/CompressingUtils.java:128

                "ISO-8859-1",
                "ISO-8859-5",
                "ISO-8859-7",
                "ISO-8859-8",
                "UTF-16LE", "UTF-16BE",
                "UTF-32LE", "UTF-32BE"
        };

        for (String candidate : candidates) {
            try {
                Charset charset = Charset.forName(candidate);
                if (!charset.equals(OperatingSystem.NATIVE_CHARSET) && testEncoding(zipFile, charset)) {
                    return charset;
                }
            } catch (IllegalArgumentException ignored) {
            }
        }

        throw new IOException("Cannot find suitable encoding for the zip.");
    }

    public static ZipFileTree openZipTree(Path zipFile) throws IOException {
        return new ZipFileTree(openZipFile(zipFile));
    }

    public static ZipArchiveReader openZipFile(Path zipFile) throws IOException {
        return openZipFileWithPossibleEncoding(zipFile, StandardCharsets.UTF_8);
    }

    public static ZipArchiveReader openZipFile(Path zipFile, Charset charset) throws IOException {
        return new ZipArchiveReader(zipFile, charset, true, true);
    }

    public static ZipArchiveReader openZipFileWithPossibleEncoding(Path zipFile, Charset possibleEncoding) throws IOException {
        if (possibleEncoding == null)
            possibleEncoding = StandardCharsets.UTF_8;

View on GitHub (pinned to 24702dc5a0)