quarkusio/quarkus · error · RegistryResolutionException

Failed to resolve ${coords} locally

Error message

Failed to resolve ${coords} locally

What it means

Thrown by MavenRegistryCache.clearCache when it tries to locate the local Maven repository directory of an artifact to evict it from the cache. resolver.findArtifactDirectory wrapped a BootstrapMavenException, meaning the artifact could not be located/resolved locally, so the cache-clearing operation aborts with this RegistryResolutionException naming the artifact coords.

Source

Thrown at independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/client/maven/MavenRegistryCache.java:53

        }
        if (config.getPlatforms() != null) {
            artifacts.add(config.getPlatforms().getArtifact());
        }
        this.artifacts = artifacts;
        this.resolver = Objects.requireNonNull(resolver);
        this.log = Objects.requireNonNull(log);
    }

    @Override
    public void clearCache() throws RegistryResolutionException {
        log.debug("%s clearCache", config.getId());
        for (ArtifactCoords coords : artifacts) {
            final Path dir;
            try {
                dir = resolver.findArtifactDirectory(new DefaultArtifact(coords.getGroupId(), coords.getArtifactId(),
                        coords.getClassifier(), coords.getType(), coords.getVersion()));
            } catch (BootstrapMavenException e) {
                throw new RegistryResolutionException("Failed to resolve " + coords + " locally", e);
            }
            if (Files.exists(dir)) {
                try (Stream<Path> dirPaths = Files.list(dir)) {
                    dirPaths.forEach(path -> {
                        try {
                            Files.delete(path);
                        } catch (IOException e) {
                        }
                    });
                } catch (IOException e) {
                    throw new RegistryResolutionException("Failed to read directory " + dir, e);
                }
            }
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Verify the artifact actually exists in the local repository (ls ~/.m2/repository/<group-path>/<artifact>/<version>); if it is already gone, no clearing is needed.
2. Correct the ArtifactCoords passed to clearCache — check groupId/artifactId/version spelling and that the version was ever downloaded.
3. Point the resolver at the same local repository (maven.repo.local) used when the artifacts were first downloaded.
4. Re-download the artifact first (mvn dependency:get) if you intend to purge and refresh it.
5. Consider treating missing artifacts as a no-op by checking existence before calling clearCache.

Example fix

// before: clearing unconditionally, aborts when artifact is absent
cache.clearCache(List.of(ArtifactCoords.jar("io.quarkus", "quarkus-core", "3.2.5.Final")));
// after: only clear artifacts that resolve locally
if (resolver.hasArtifact(coords)) { // or wrap per-artifact
    cache.clearCache(List.of(coords));
}

// verify the artifact exists in the local repo before calling clearCache
Path expectedDir = Path.of(
    System.getProperty("maven.repo.local", System.getProperty("user.home") + "/.m2/repository"),
    coords.getGroupId().replace('.', '/'),
    coords.getArtifactId(), coords.getVersion());
if (!Files.isDirectory(expectedDir)) {
    // nothing to clear — skip instead of triggering the error
    return;
}

static boolean artifactCachedLocally(ArtifactCoords coords) {
    Path dir = Path.of(System.getProperty("maven.repo.local",
            System.getProperty("user.home") + "/.m2/repository"))
        .resolve(coords.getGroupId().replace('.', '/'))
        .resolve(coords.getArtifactId())
        .resolve(coords.getVersion());
    return Files.isDirectory(dir);
}

try {
    cache.clearCache(artifacts);
} catch (RegistryResolutionException e) {
    if (e.getMessage().startsWith("Failed to resolve") && e.getMessage().contains("locally")) {
        log.warn("Artifact not in local repo, skipping: " + e.getMessage()); // already gone — treat as cleared
    } else throw e;
}

When it happens

Trigger: Calling MavenRegistryCache.clearCache with a list of ArtifactCoords where at least one artifact is not present in (or not resolvable from) the local Maven repository — findArtifactDirectory throws BootstrapMavenException before any deletion can happen.

Common situations: Clearing the registry cache after the artifacts were already deleted by a previous clearCache run or manual cleanup; typos or stale coordinates in the artifact list (e.g. a version that was never downloaded); running against a different/empty -Dmaven.repo.local directory than the one used previously.

Related errors

• Failed to cache a new instance of io.quarkus.maven.QuarkusMa
• Cached artifact does not exist: ${p}
• Failed to resolve artifact ${artifact}
• Failed to resolve
• Has not been previously resolved

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