quarkusio/quarkus · error · BootstrapMavenException

Failed to install ${artifact}

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.

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)

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

• Has not been previously resolved
• Failed to resolve ${coords} locally
• Unable to determine groupId and artifactId of the jar that c
• Unable to determine groupId and artifactId of the extension
• Unable to determine groupId and artifactId of the jar that c

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