{"record":{"id":"9bb277df7a6992f4","repo":"quarkusio/quarkus","slug":"maven-lib-dir-does-not-exist-mvnlib","errorCode":null,"errorMessage":"Maven lib dir does not exist: ${mvnLib}","messagePattern":"Maven lib dir does not exist: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"independent-projects/bootstrap/maven-resolver/src/main/java/io/quarkus/bootstrap/resolver/maven/options/BootstrapMavenOptions.java","lineNumber":79,"sourceCode":"            throw new IllegalArgumentException(\"Invalid command line: \" + cmdLine, e);\n        }\n\n        if (args.length == 0) {\n            return Collections.emptyMap();\n        }\n\n        final String mavenHome = PropertyUtils.getProperty(\"maven.home\");\n        if (mavenHome == null) {\n            try {\n                return invokeParser(Thread.currentThread().getContextClassLoader(), args);\n            } catch (ClassNotFoundException e) {\n                throw new RuntimeException(\"Failed to load parser\", e);\n            }\n        }\n\n        final Path mvnLib = Paths.get(mavenHome).resolve(\"lib\");\n        if (!Files.exists(mvnLib)) {\n            throw new IllegalStateException(\"Maven lib dir does not exist: \" + mvnLib);\n        }\n        final URL[] urls;\n        try (Stream<Path> files = Files.list(mvnLib)) {\n            final List<URL> list = files.map(p -> {\n                try {\n                    return p.toUri().toURL();\n                } catch (MalformedURLException e) {\n                    throw new IllegalStateException(\"Failed to translate \" + p + \" to URL\", e);\n                }\n            }).collect(Collectors.toCollection(ArrayList::new));\n\n            list.add(getClassOrigin(BootstrapMavenOptions.class).toUri().toURL());\n            urls = list.toArray(new URL[list.size()]);\n\n        } catch (Exception e) {\n            throw new IllegalStateException(\"Failed to create a URL list out of \" + mvnLib + \" content\", e);\n        }\n        final ClassLoader originalCl = Thread.currentThread().getContextClassLoader();","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/independent-projects/bootstrap/maven-resolver/src/main/java/io/quarkus/bootstrap/resolver/maven/options/BootstrapMavenOptions.java#L61-L97","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify mvn -version reports a correct Maven home and that <maven home>/lib exists with the maven jars","Set/fix the Maven home source (M2_HOME or the path logic used by the resolver) to a full Apache Maven distribution","Re-install a complete Maven distribution (unzip apache-maven-x.y.z-bin.tar.gz) - do not point at bin/ or a shim script","In containers, bake the full Maven distribution into the image instead of relying on ephemeral downloads"],"exampleFix":"// before\nexport M2_HOME=/usr/bin   # no lib/ here\n// after\nexport M2_HOME=/opt/apache-maven-3.9.9  # contains lib/\nls \"$M2_HOME/lib\" | grep plexus","handlingStrategy":"validation","validationCode":"String mavenHome = System.getenv(\"M2_HOME\"); // or however home is derived\nif (mavenHome == null || !Files.isDirectory(Path.of(mavenHome, \"lib\"))) {\n    throw new IllegalStateException(\n        \"Maven home is not a full distribution (missing lib/): \" + mavenHome);\n}","typeGuard":null,"tryCatchPattern":"try {\n    BootstrapMavenOptions options = BootstrapMavenOptions.newInstance(cmdLine);\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"Maven lib dir does not exist\")) {\n        throw new IllegalStateException(\"Set M2_HOME to a full Apache Maven distribution\", e);\n    }\n    throw e;\n}","preventionTips":["Always install the complete Apache Maven binary distribution, not just the mvn binary","Verify `mvn -version` Maven home contains lib/ before embedding the resolver","Bake the full Maven distribution into container images at build time","Do not point M2_HOME at wrapper shims or package-manager symlink farms"],"tags":["maven","installation","environment","classpath"],"backgroundTag":"maven-home-misconfigured","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}