{"record":{"id":"8d0337d12999fab9","repo":"quarkusio/quarkus","slug":"failed-to-install-artifact","errorCode":null,"errorMessage":"Failed to install ${artifact}","messagePattern":"Failed to install (.+?)","errorType":"exception","errorClass":"BootstrapMavenException","httpStatus":null,"severity":"error","filePath":"independent-projects/bootstrap/maven-resolver/src/main/java/io/quarkus/bootstrap/resolver/maven/MavenArtifactResolver.java","lineNumber":361,"sourceCode":"            request.setRoot(new Dependency(artifact, JavaScopes.COMPILE, false, exclusions));\n        }\n        return request;\n    }\n\n    public List<RemoteRepository> newResolutionRepositories(List<RemoteRepository> repos) {\n        return repos.isEmpty() ? List.of() : repoSystem.newResolutionRepositories(repoSession, repos);\n    }\n\n    public List<RemoteRepository> aggregateRepositories(List<RemoteRepository> dominant, List<RemoteRepository> recessive) {\n        return dominant.isEmpty() ? recessive\n                : remoteRepoManager.aggregateRepositories(repoSession, dominant, recessive, false);\n    }\n\n    public void install(Artifact artifact) throws BootstrapMavenException {\n        try {\n            repoSystem.install(repoSession, new InstallRequest().addArtifact(artifact));\n        } catch (InstallationException ex) {\n            throw new BootstrapMavenException(\"Failed to install \" + artifact, ex);\n        }\n    }\n\n    private CollectRequest newCollectRequest(Artifact artifact, List<RemoteRepository> mainRepos) {\n        return newCollectRequest(artifact, mainRepos, List.of());\n    }\n\n    private CollectRequest newCollectRequest(Artifact artifact, List<RemoteRepository> mainRepos,\n            Collection<Exclusion> exclusions) {\n        return new CollectRequest()\n                .setRoot(new Dependency(artifact, JavaScopes.RUNTIME, false, exclusions))\n                .setRepositories(aggregateRepositories(mainRepos, remoteRepos));\n    }\n\n    private static ArtifactKey getKey(Artifact a) {\n        return DependencyUtils.getKey(a);\n    }\n}","sourceCodeStart":343,"sourceCodeEnd":379,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/independent-projects/bootstrap/maven-resolver/src/main/java/io/quarkus/bootstrap/resolver/maven/MavenArtifactResolver.java#L343-L379","documentation":"MavenArtifactResolver.install() asks the underlying Maven Resolver (repoSystem) to install an artifact into the local repository, and the resolver threw an InstallationException. BootstrapMavenException wraps it with the failing artifact coordinates in the message. This library throws it to turn Maven Resolver's checked exception into the bootstrap layer's uniform exception type.","triggerScenarios":"Calling MavenArtifactResolver.install(Artifact) when the local repository directory is not writable, the artifact file does not exist on disk, the local repo metadata is corrupted/locked, or another process holds a lock on the artifact in ~/.m2/repository.","commonSituations":"Read-only or full ~/.m2/repository (CI containers running as non-root), concurrent Quarkus builds racing on the same local repo, an artifact jar deleted or truncated after resolution, corrupted _remote.repositories metadata after switching between repo managers.","solutions":["Check that the local Maven repository path exists and is writable by the current user; fix permissions or free disk space","Remove the specific artifact directory under ~/.m2/repository (or the whole repository cache) and retry so it is reinstalled cleanly","Ensure no concurrent Maven/Quarkus processes are using the same local repo; set a distinct quarkus.maven.repo or -Dmaven.repo.local per process","Inspect the cause (InstallationException) for the exact artifact file and validate the Artifact has a real, existing file attached before calling install()"],"exampleFix":"// before\nresolver.install(new DefaultArtifact(\"com.acme\", \"app\", null, \"jar\", \"1.0\", null, (File) null));\n// after\nFile jar = new File(\"target/app-1.0.jar\");\nif (!jar.isFile()) {\n    throw new IllegalStateException(\"Artifact file missing: \" + jar);\n}\nresolver.install(new DefaultArtifact(\"com.acme\", \"app\", null, \"jar\", \"1.0\", null, jar));","handlingStrategy":"try-catch","validationCode":"Path localRepo = Path.of(System.getProperty(\"user.home\"), \".m2\", \"repository\");\nif (!Files.isDirectory(localRepo) || !Files.isWritable(localRepo)) {\n    throw new IllegalStateException(\"Local repo missing or not writable: \" + localRepo);\n}\nif (artifact.getFile() == null || !artifact.getFile().isFile()) {\n    throw new IllegalStateException(\"Artifact file missing: \" + artifact);\n}","typeGuard":null,"tryCatchPattern":"try {\n    resolver.install(artifact);\n} catch (BootstrapMavenException e) {\n    log.error(\"Install failed for %s: %s\", artifact, e.getCause());\n    // optionally clean the artifact's local repo dir and retry once\n    throw e;\n}","preventionTips":["Keep the local Maven repository writable and with free disk space, especially in CI containers","Avoid concurrent builds sharing one local repo; give each process its own -Dmaven.repo.local","Always attach an existing file to the Artifact before calling install()","Clear corrupted artifact directories instead of the whole repo when possible"],"tags":["maven","local-repository","artifact-install"],"backgroundTag":"maven-artifact-install-failed","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}