{"record":{"id":"1643ed105939d6fc","repo":"quarkusio/quarkus","slug":"failed-to-initialize-maven-repository-system","errorCode":null,"errorMessage":"Failed to initialize Maven repository system","messagePattern":"Failed to initialize Maven repository system","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"devtools/maven/src/main/java/io/quarkus/maven/components/QuarkusWorkspaceProvider.java","lineNumber":74,"sourceCode":"            SettingsDecrypter settingsDecrypter) {\n        this.versionResolver = versionResolver;\n        this.versionRangeResolver = versionRangeResolver;\n        this.artifactResolver = artifactResolver;\n        this.metadataResolver = metadataResolver;\n        this.deployer = deployer;\n        this.remoteRepoManager = remoteRepoManager;\n        this.settingsDecrypter = settingsDecrypter;\n    }\n\n    public BootstrapMavenContext getMavenContext() {\n        return ctx == null ? ctx = createMavenContext(BootstrapMavenContext.config()) : ctx;\n    }\n\n    public RepositorySystem getRepositorySystem() {\n        try {\n            return getMavenContext().getRepositorySystem();\n        } catch (BootstrapMavenException e) {\n            throw new RuntimeException(\"Failed to initialize Maven repository system\", e);\n        }\n    }\n\n    public RemoteRepositoryManager getRemoteRepositoryManager() {\n        return remoteRepoManager;\n    }\n\n    public BootstrapMavenContext createMavenContext(BootstrapMavenContextConfig<?> config) {\n        try {\n            return new BootstrapMavenContext(config) {\n                @Override\n                protected MavenFactory configureMavenFactory() {\n                    final BootstrapMavenContext ctx = this;\n                    return MavenFactory.create(\n                            List.of(RepositorySystem.class.getClassLoader(),\n                                    getClass().getClassLoader()),\n                            builder -> builder.addBeanInstance(versionResolver)\n                                    .addBeanInstance(versionRangeResolver)","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/devtools/maven/src/main/java/io/quarkus/maven/components/QuarkusWorkspaceProvider.java#L56-L92","documentation":"QuarkusWorkspaceProvider.getRepositorySystem lazily bootstraps a QuarkusWorkspaceProvider/MavenContext; if that bootstrap throws BootstrapMavenException, it is wrapped in a RuntimeException('Failed to initialize Maven repository system'). It means the Maven resolver infrastructure (RepositorySystem) could not be created — typically because the underlying Maven context (local repo, settings.xml, Maven home) could not be initialized.","triggerScenarios":"Calling getRepositorySystem() (directly or via Quarkus Maven goals) when getMavenContext().getRepositorySystem() fails: unreadable or invalid ~/.m2/settings.xml, missing/corrupt local repository, no Maven installation found (MAVEN_HOME/M2_HOME issues), or an unsupported Maven distribution layout.","commonSituations":"Broken MAVEN_HOME or mvn wrapper; malformed settings.xml (invalid XML, bad mirror/repository syntax); local repo path pointing to an unwritable or nonexistent directory; running the tool outside a normal Maven environment (e.g. minimal container without ~/.m2).","solutions":["Run `mvn -X help:effective-settings` to verify Maven and settings.xml are valid; fix any XML/syntax errors in ~/.m2/settings.xml.","Check MAVEN_HOME/M2_HOME and that `mvn -v` works; use the Maven wrapper (./mvnw) if the system Maven is broken or missing.","Verify the local repository path in settings.xml (-Dmaven.repo.local) exists and is writable; delete a corrupt ~/.m2/repository metadata if needed.","Run with more logging (mvn -X / -e) to surface the underlying BootstrapMavenException cause."],"exampleFix":"// before: broken settings.xml\n<settings><mirrors><mirror><id>m1</id></mirror></mirrors></settings>\n// after: valid mirror entry\n<settings><mirrors><mirror><id>m1</id><mirrorOf>central</mirrorOf><url>https://repo.maven.apache.org/maven2</url></mirror></mirrors></settings>","handlingStrategy":"try-catch","validationCode":"// preflight checks before invoking Quarkus tooling\nassert new File(System.getProperty(\"user.home\"), \".m2/settings.xml\").exists()\n       || true; // settings optional, but if present must parse\nProcess p = new ProcessBuilder(\"mvn\", \"-v\").start();\nif (p.waitFor() != 0) throw new IllegalStateException(\"Maven not available\");","typeGuard":null,"tryCatchPattern":"try {\n    RepositorySystem rs = workspaceProvider.getRepositorySystem();\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Failed to initialize Maven repository system\")) {\n        throw new IllegalStateException(\"Check MAVEN_HOME and ~/.m2/settings.xml: \" + e.getCause(), e);\n    }\n    throw e;\n}","preventionTips":["Keep ~/.m2/settings.xml valid and minimal; validate it with mvn help:effective-settings","Ensure mvn -v works and MAVEN_HOME/M2_HOME are set correctly","Verify the local repository directory exists and is writable","In containers, bake a sane ~/.m2 setup into the image"],"tags":["maven","bootstrap","repository-system","environment"],"backgroundTag":"maven-bootstrap-failure","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}