quarkusio/quarkus · error · IOException

Failed to locate <name> in <zip>

Error message

Failed to locate <name> in <zip>

What it means

ZipResourceLoader.loadResourceAsPath opens the configured zip file as a FileSystem and looks up the named entry at its root. If the entry does not exist, an IOException 'Failed to locate <name> in <zip>' is thrown so the caller can fall back to another loader.

Source

Thrown at independent-projects/tools/devtools-common/src/main/java/io/quarkus/platform/descriptor/loader/json/ZipResourceLoader.java:23

import java.nio.file.Files;
import java.nio.file.Path;

import io.quarkus.fs.util.ZipUtils;

public class ZipResourceLoader implements ResourceLoader {

    private final Path zip;

    public ZipResourceLoader(Path zip) {
        this.zip = zip;
    }

    @Override
    public <T> T loadResourceAsPath(String name, ResourcePathConsumer<T> consumer) throws IOException {
        try (FileSystem fs = ZipUtils.newFileSystem(zip)) {
            final Path path = fs.getPath("/", name);
            if (!Files.exists(path)) {
                throw new IOException("Failed to locate " + name + " in " + zip);
            }
            return consumer.consume(path);
        }
    }

}

View on GitHub (pinned to e1c734241f)

Solutions

1. List the archive contents (`unzip -l <zip>`) and confirm the exact entry name and case
2. Check the artifact version — the resource name may have changed across Quarkus versions (e.g. quarkus-extension.json vs .yaml)
3. Ensure `name` is an absolute path within the zip as expected by fs.getPath("/", name)

Example fix

// before
loader.loadResourceAsPath("quarkus-extension.yaml", c); // entry is quarkus-extension.json
// after
loader.loadResourceAsPath("META-INF/quarkus-extension.json", c);

static boolean zipContains(Path zip, String name) throws IOException {
    try (FileSystem fs = ZipUtils.newFileSystem(zip)) {
        return Files.exists(fs.getPath("/", name));
    }
}

try {
    return loader.loadResourceAsPath(name, consumer);
} catch (IOException e) {
    if (e.getMessage().startsWith("Failed to locate")) {
        return fallbackLoader.loadResourceAsPath(fallbackName(name), consumer); // e.g. .json variant
    }
    throw e;
}

When it happens

Trigger: Calling loadResourceAsPath(name, consumer) where name is not a path inside the zip — wrong resource name, wrong case, missing leading path segments, or the entry exists only in a newer/older version of the archive.

Common situations: Expecting quarkus-extension.yaml in a JAR that actually contains quarkus-extension.json (Quarkus <=1.x vs newer); typo in the resource path; the zip is a different artifact than assumed.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Error unzipping import file %s: %s
• Failed to read
• Failed to read
• Failed to read <jar>
• Failed to open path tree with root %s

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