quarkusio/quarkus · error · IllegalStateException

Maven lib dir does not exist: ${mvnLib}

Error message

Maven lib dir does not exist: ${mvnLib}

What it means

BootstrapMavenOptions.parse locates the Maven installation via mavenHome and expects a lib/ subdirectory containing the Maven jars it loads to parse command line options. If <mavenHome>/lib does not exist it throws IllegalStateException. The parser classes are loaded from that directory, so it is mandatory.

Source

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

            throw new IllegalArgumentException("Invalid command line: " + cmdLine, e);
        }

        if (args.length == 0) {
            return Collections.emptyMap();
        }

        final String mavenHome = PropertyUtils.getProperty("maven.home");
        if (mavenHome == null) {
            try {
                return invokeParser(Thread.currentThread().getContextClassLoader(), args);
            } catch (ClassNotFoundException e) {
                throw new RuntimeException("Failed to load parser", e);
            }
        }

        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();

View on GitHub (pinned to e1c734241f)

Solutions

1. Verify mvn -version reports a correct Maven home and that <maven home>/lib exists with the maven jars
2. Set/fix the Maven home source (M2_HOME or the path logic used by the resolver) to a full Apache Maven distribution
3. Re-install a complete Maven distribution (unzip apache-maven-x.y.z-bin.tar.gz) - do not point at bin/ or a shim script
4. In containers, bake the full Maven distribution into the image instead of relying on ephemeral downloads

Example fix

// before
export M2_HOME=/usr/bin   # no lib/ here
// after
export M2_HOME=/opt/apache-maven-3.9.9  # contains lib/
ls "$M2_HOME/lib" | grep plexus

String mavenHome = System.getenv("M2_HOME"); // or however home is derived
if (mavenHome == null || !Files.isDirectory(Path.of(mavenHome, "lib"))) {
    throw new IllegalStateException(
        "Maven home is not a full distribution (missing lib/): " + mavenHome);
}

try {
    BootstrapMavenOptions options = BootstrapMavenOptions.newInstance(cmdLine);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Maven lib dir does not exist")) {
        throw new IllegalStateException("Set M2_HOME to a full Apache Maven distribution", e);
    }
    throw e;
}

When it happens

Trigger: Calling BootstrapMavenOptions.newInstance()/parse() when the derived Maven home (e.g. from M2_HOME or the mvn executable location) points at a directory without a lib/ folder - such as a bare binary install, a partially extracted distribution, or a wrapper script shim.

Common situations: M2_HOME pointing to the wrong directory, using a minimal/Maven-removed distro (e.g. only the mvn wrapper), installing Maven via a package manager that layouts files differently, or a deleted/cleaned CI cache of the Maven distribution.

Related errors

• Failed to create a URL list out of ${mvnLib} content
• Unable to find a template for these candidates ${candidates}
• Failed to resolve maven plugin version containing <cls>
• Failed to locate io.quarkus:quarkus-core-deployment on the a
• Failed to locate <pomPropsPath> on the classpath

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