quarkusio/quarkus · error · RuntimeException

Unable to initialize ZipFileSystem: ${archivePath}

Error message

Unable to initialize ZipFileSystem: ${archivePath}

What it means

Thrown by the ZipFileSystemArchiveCreator constructor when ZipUtils.createNewReproducibleZipFileSystem cannot open a reproducible ZIP filesystem over the target archive path, wrapping the IOException in a RuntimeException. Without this filesystem no jar entries can be written.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/pkg/jar/ZipFileSystemArchiveCreator.java:45

    private static final Logger LOG = Logger.getLogger(ZipFileSystemArchiveCreator.class);

    // we probably don't need the Windows entry but let's be safe
    private static final Set<String> MANIFESTS = Set.of("META-INF/MANIFEST.MF", "META-INF\\MANIFEST.MF");

    private final FileSystem zipFileSystem;

    private final Map<String, String> addedFiles = new HashMap<>();

    public ZipFileSystemArchiveCreator(Path archivePath, boolean compressed, Instant entryTimestamp) {
        try {
            if (compressed) {
                zipFileSystem = ZipUtils.createNewReproducibleZipFileSystem(archivePath, entryTimestamp);
            } else {
                zipFileSystem = ZipUtils.createNewReproducibleZipFileSystem(archivePath, Map.of("compressionMethod", "STORED"),
                        entryTimestamp);
            }
        } catch (IOException e) {
            throw new RuntimeException("Unable to initialize ZipFileSystem: " + archivePath, e);
        }
    }

    @Override
    public void addManifest(Manifest manifest) throws IOException {
        Path manifestInFsPath = zipFileSystem.getPath("META-INF", "MANIFEST.MF");
        handleParentDirectories(manifestInFsPath, CURRENT_APPLICATION);
        try (final OutputStream os = Files.newOutputStream(manifestInFsPath)) {
            manifest.write(os);
        }
    }

    @Override
    public void addDirectory(String directory, String source) throws IOException {
        if (addedFiles.putIfAbsent(directory, source) != null) {
            return;
        }
        final Path targetInFsPath = zipFileSystem.getPath(directory);

View on GitHub (pinned to e1c734241f)

Solutions

1. Verify the archivePath parent directory exists and is writable.
2. Make sure no other process holds the target jar open; stop the dev-mode app before packaging.
3. Run mvn clean to delete a corrupt/stale jar, then rebuild.
4. Check the wrapped IOException message for the concrete filesystem error (e.g. 'File already exists', 'Access denied').
5. Update/verify the JDK — zip filesystem provider bugs in some JDK builds can fail reproducible zips.

Path archive = Path.of("target/quarkus-app/quarkus-run.jar");
if (!Files.isWritable(archive.getParent())) throw new IllegalStateException("Output dir not writable");
try (var ignored = FileChannel.open(archive.toAbsolutePath().normalize(),
        StandardOpenOption.CREATE, StandardOpenOption.WRITE, StandardOpenOption.DELETE_ON_CLOSE)) {
    // OK: file is lockable/writable
} catch (IOException e) { throw new IllegalStateException("Archive path unusable", e); }

try {
    // package step
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unable to initialize ZipFileSystem")) {
        log.error("ZipFileSystem init failed", e.getCause());
        // mvn clean, unlock file, verify JDK, retry
    } else throw e;
}

When it happens

Trigger: Package step selecting the zipfs archive creator and creating the jar fails: invalid/unwritable archivePath, missing parent directories, file locked by another process, or unsupported/failed ZipFileSystem provider creation.

Common situations: Unwritable or already-open target jar (running app, IDE indexers); path length/permission problems on Windows; customized quarkus.package settings redirecting output to an invalid path; JDK issues with the zipfs provider.

Related errors

• Error joining byte arrays
• Unable to create archive: ${archivePath}
• Error joining byte arrays
• Error creating the openshift binary build archive.
• Failed to open path tree with root %s

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/57e565cf8a2ff2cd. Report an issue: GitHub.