quarkusio/quarkus · error · BootstrapMavenException

Failed to install

Error message

Failed to install ${artifact}

What it means

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.

Solutions

1. Check that the local Maven repository path exists and is writable by the current user; fix permissions or free disk space
2. Remove the specific artifact directory under ~/.m2/repository (or the whole repository cache) and retry so it is reinstalled cleanly
3. Ensure no concurrent Maven/Quarkus processes are using the same local repo; set a distinct quarkus.maven.repo or -Dmaven.repo.local per process
4. Inspect the cause (InstallationException) for the exact artifact file and validate the Artifact has a real, existing file attached before calling install()

Example fix

// before
resolver.install(new DefaultArtifact("com.acme", "app", null, "jar", "1.0", null, (File) null));
// after
File jar = new File("target/app-1.0.jar");
if (!jar.isFile()) {
    throw new IllegalStateException("Artifact file missing: " + jar);
}
resolver.install(new DefaultArtifact("com.acme", "app", null, "jar", "1.0", null, jar));

Path localRepo = Path.of(System.getProperty("user.home"), ".m2", "repository");
if (!Files.isDirectory(localRepo) || !Files.isWritable(localRepo)) {
    throw new IllegalStateException("Local repo missing or not writable: " + localRepo);
}
if (artifact.getFile() == null || !artifact.getFile().isFile()) {
    throw new IllegalStateException("Artifact file missing: " + artifact);
}

try {
    resolver.install(artifact);
} catch (BootstrapMavenException e) {
    log.error("Install failed for %s: %s", artifact, e.getCause());
    // optionally clean the artifact's local repo dir and retry once
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to resolve locally
• Has not been previously resolved
• (aggregated Maven build error messages accumulated in the…
• An error occurred attempting to resolve effective POM
• appArtifact expression

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

Appendix: source

Thrown at independent-projects/bootstrap/maven-resolver/src/main/java/io/quarkus/bootstrap/resolver/maven/MavenArtifactResolver.java:361

            request.setRoot(new Dependency(artifact, JavaScopes.COMPILE, false, exclusions));
        }
        return request;
    }

    public List<RemoteRepository> newResolutionRepositories(List<RemoteRepository> repos) {
        return repos.isEmpty() ? List.of() : repoSystem.newResolutionRepositories(repoSession, repos);
    }

    public List<RemoteRepository> aggregateRepositories(List<RemoteRepository> dominant, List<RemoteRepository> recessive) {
        return dominant.isEmpty() ? recessive
                : remoteRepoManager.aggregateRepositories(repoSession, dominant, recessive, false);
    }

    public void install(Artifact artifact) throws BootstrapMavenException {
        try {
            repoSystem.install(repoSession, new InstallRequest().addArtifact(artifact));
        } catch (InstallationException ex) {
            throw new BootstrapMavenException("Failed to install " + artifact, ex);
        }
    }

    private CollectRequest newCollectRequest(Artifact artifact, List<RemoteRepository> mainRepos) {
        return newCollectRequest(artifact, mainRepos, List.of());
    }

    private CollectRequest newCollectRequest(Artifact artifact, List<RemoteRepository> mainRepos,
            Collection<Exclusion> exclusions) {
        return new CollectRequest()
                .setRoot(new Dependency(artifact, JavaScopes.RUNTIME, false, exclusions))
                .setRepositories(aggregateRepositories(mainRepos, remoteRepos));
    }

    private static ArtifactKey getKey(Artifact a) {
        return DependencyUtils.getKey(a);
    }
}

View on GitHub (pinned to e1c734241f)