HMCL-dev/HMCL · critical · FileSystemNotFoundException

Module jdk.zipfs does not exist

Error message

Module jdk.zipfs does not exist

What it means

createZipFileSystem opens a zip via the jdk.zipfs NIO file-system provider, resolved statically. If the provider is absent — the JVM was started with --limit-modules / -p restrictions or runs on a stripped JRE without jdk.zipfs — the method throws FileSystemNotFoundException with this message (later wrapped as a ZipException 'Java Environment is broken' only for provider-lookup failures; the direct throw surfaces as FileSystemNotFoundException).

Solutions

  1. Include jdk.zipfs in the runtime: run with --add-modules jdk.zipfs or add it to the jlink command (jlink --add-modules ...,jdk.zipfs).
  2. Switch to a full JRE/JDK that ships jdk.zipfs.
  3. Fall back to java.util.zip.ZipFile-based access instead of the NIO zip filesystem when the provider is unavailable.

Example fix

// before
java -jar app.jar // minimal runtime, no jdk.zipfs

// after
java --add-modules jdk.zipfs -jar app.jar
// or at build time:
jlink --add-modules java.base,jdk.zipfs --output runtime
Defensive patterns

Strategy: fallback

Validate before calling

static boolean zipfsAvailable() { try { Class.forName("jdk.nio.zipfs.ZipFileSystemProvider"); return true; } catch (ClassNotFoundException e) { return false; } }

Try / catch

try { return CompressingUtils.createReadOnlyZipFileSystem(path); } catch (FileSystemNotFoundException e) { log.warn("jdk.zipfs missing; falling back to ZipFile", e); return null; }

Prevention

When it happens

Trigger: Running on a custom/minimal JRE without jdk.zipfs, or launching with module flags (--limit-modules, --add-modules omitted) that exclude jdk.zipfs, then calling createZipFileSystem via createReadOnlyZipFileSystem/createWritableZipFileSystem.

Common situations: Bundling the app with jlink and forgetting to include jdk.zipfs; custom runtime images for distribution; security-hardened JVMs with restricted module graphs.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

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

    public static FileSystem createWritableZipFileSystem(Path zipFile) throws IOException {
        return createWritableZipFileSystem(zipFile, null);
    }

    public static FileSystem createWritableZipFileSystem(Path zipFile, Charset charset) throws IOException {
        return createZipFileSystem(zipFile, true, true, charset);
    }

    public static FileSystem createZipFileSystem(Path zipFile, boolean create, boolean useTempFile, Charset encoding) throws IOException {
        Map<String, Object> env = new HashMap<>();
        if (create)
            env.put("create", "true");
        if (encoding != null)
            env.put("encoding", encoding.name());
        if (useTempFile)
            env.put("useTempFile", true);
        try {
            if (ZIPFS_PROVIDER == null)
                throw new FileSystemNotFoundException("Module jdk.zipfs does not exist");

            return ZIPFS_PROVIDER.newFileSystem(zipFile, env);
        } catch (UnsupportedOperationException ex) {
            throw new ZipException("Not a zip file");
        } catch (FileSystemNotFoundException ex) {
            throw Lang.apply(new ZipException("Java Environment is broken"), it -> it.initCause(ex));
        }
    }

    /**
     * Read the text content of a file in zip.
     *
     * @param zipFile the zip file
     * @param name    the location of the text in zip file, something like A/B/C/D.txt
     * @return the plain text content of given file.
     * @throws IOException if the file is not a valid zip file.
     */
    public static String readTextZipEntry(Path zipFile, String name) throws IOException {

View on GitHub (pinned to 24702dc5a0)