quarkusio/quarkus · error · IllegalStateException

Failed to create a URL list out of ${mvnLib} content

Error message

Failed to create a URL list out of ${mvnLib} content

What it means

After collecting URLs for every jar in the Maven lib directory plus the origin of BootstrapMavenOptions itself, parse() builds a URLClassLoader to invoke the Maven option parser. Any exception while listing/collecting the URLs (I/O errors, invalid paths, toURL failures) is wrapped in IllegalStateException 'Failed to create a URL list out of <mvnLib> content'.

Source

Thrown at independent-projects/bootstrap/maven-resolver/src/main/java/io/quarkus/bootstrap/resolver/maven/options/BootstrapMavenOptions.java:95

        final Path mvnLib = Paths.get(mavenHome).resolve("lib");
        if (!Files.exists(mvnLib)) {
            throw new IllegalStateException("Maven lib dir does not exist: " + mvnLib);
        }
        final URL[] urls;
        try (Stream<Path> files = Files.list(mvnLib)) {
            final List<URL> list = files.map(p -> {
                try {
                    return p.toUri().toURL();
                } catch (MalformedURLException e) {
                    throw new IllegalStateException("Failed to translate " + p + " to URL", e);
                }
            }).collect(Collectors.toCollection(ArrayList::new));

            list.add(getClassOrigin(BootstrapMavenOptions.class).toUri().toURL());
            urls = list.toArray(new URL[list.size()]);

        } catch (Exception e) {
            throw new IllegalStateException("Failed to create a URL list out of " + mvnLib + " content", e);
        }
        final ClassLoader originalCl = Thread.currentThread().getContextClassLoader();
        try (URLClassLoader ucl = new URLClassLoader(urls, null)) {
            Thread.currentThread().setContextClassLoader(ucl);
            try {
                return invokeParser(ucl, args);
            } catch (ClassNotFoundException e) {
                Thread.currentThread().setContextClassLoader(originalCl);
                try {
                    return invokeParser(originalCl, args);
                } catch (ClassNotFoundException classNotFoundException) {
                    throw new RuntimeException("Failed to load parser", e);
                }
            }
        } catch (IOException e) {
            throw new IllegalStateException("Failed to close URL classloader", e);
        } finally {
            Thread.currentThread().setContextClassLoader(originalCl);

View on GitHub (pinned to e1c734241f)

Solutions

1. Check read/execute permissions on <mavenHome>/lib and its files for the current user
2. Inspect the wrapped cause to see which file failed; replace broken symlinks or reinstall the Maven distribution
3. Avoid spaces/special characters in the Maven installation path or quote/escape them properly
4. Ensure quarkus-bootstrap classes are on the classpath in a form whose origin can be located (directory or jar), not an unsupported launcher

Example fix

// before
chmod 700 /opt/apache-maven/lib   // parser user cannot read
// after
chmod 755 /opt/apache-maven/lib && chmod 644 /opt/apache-maven/lib/*.jar

Path mvnLib = Path.of(mavenHome, "lib");
if (!Files.isReadable(mvnLib) || !Files.isDirectory(mvnLib)) {
    throw new IllegalStateException("Cannot read Maven lib dir: " + mvnLib);
}
try (Stream<Path> files = Files.list(mvnLib)) {
    files.forEach(p -> {
        if (!Files.isReadable(p)) throw new IllegalStateException("Unreadable jar: " + p);
    });
}

try {
    BootstrapMavenOptions options = BootstrapMavenOptions.newInstance(cmdLine);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Failed to create a URL list")) {
        throw new IllegalStateException("Check permissions/symlinks in Maven lib dir; cause: " + e.getCause(), e);
    }
    throw e;
}

When it happens

Trigger: Calling BootstrapMavenOptions.newInstance()/parse() when Files.list(mvnLib) fails (permission denied), a file in <mavenHome>/lib cannot be converted to a URL (unencodable path/symlink loop), or getClassOrigin(BootstrapMavenOptions.class) throws while locating the class origin.

Common situations: Maven lib directory with restrictive permissions (installed via package manager, run as another user), broken symlinks in the lib dir, paths with characters that break URI conversion, or the bootstrap classes living somewhere unlocatable (e.g. nested jar on classpath).

Related errors

• Failed to load <pomPropsPath> from the classpath
• Maven lib dir does not exist: ${mvnLib}
• Failed to read %s
• Failed to read resources from classpath
• Could not read class path resources having path '${resourceP

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