quarkusio/quarkus · error · IllegalStateException

Failed to resolve the registry client factory provider artif

Error message

Failed to resolve the registry client factory provider artifact ${providerArtifact}

What it means

Thrown as IllegalStateException when the Maven artifact resolver cannot resolve the registry client factory provider artifact (the jar containing the RegistryClientFactory provider) declared in a registry client configuration. The library downloads this provider jar from configured repositories before loading the factory via a classloader. The original BootstrapMavenException is preserved as the cause.

Source

Thrown at independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/ExtensionCatalogResolver.java:160

            return getDefaultClientFactory();
        }

        public RegistryClientFactory loadFromArtifact(RegistryConfig config, final Object providerValue) {
            ArtifactCoords providerArtifact;
            try {
                final String providerStr = (String) providerValue;
                providerArtifact = ArtifactCoords.fromString(providerStr);
            } catch (Exception e) {
                throw new IllegalStateException("Failed to process configuration of " + config.getId()
                        + " registry: failed to cast " + providerValue + " to String", e);
            }
            final File providerJar;
            try {
                providerJar = artifactResolver.resolve(new DefaultArtifact(providerArtifact.getGroupId(),
                        providerArtifact.getArtifactId(), providerArtifact.getClassifier(),
                        providerArtifact.getType(), providerArtifact.getVersion())).getArtifact().getFile();
            } catch (BootstrapMavenException e) {
                throw new IllegalStateException(
                        "Failed to resolve the registry client factory provider artifact " + providerArtifact, e);
            }
            log.debug("Loading registry client factory for %s from %s", config.getId(), providerArtifact);
            final URL url;
            try {
                url = providerJar.toURI().toURL();
            } catch (MalformedURLException e) {
                throw new IllegalStateException("Failed to translate " + providerJar + " to URL", e);
            }
            return loadFromUrl(url);
        }

        private RegistryClientFactory loadFromUrl(final URL url) {
            try {
                // here we use the classloader that loaded RegistryClientFactoryProvider instead of the TCCL
                // because, apparently, the TCCL doesn't work for this use-case from Maven plugins with extensions enabled
                final ClassLoader providerCl = new URLClassLoader(new URL[] { url },
                        RegistryClientFactoryProvider.class.getClassLoader());

View on GitHub (pinned to e1c734241f)

Solutions

1. Verify the provider artifact coordinates in the registry client configuration are correct (groupId:artifactId:classifier:type:version) and that the version exists
2. Run 'mvn dependency:get -Dartifact=<coords>' manually to confirm the artifact is resolvable from your configured repositories
3. Check settings.xml mirrors/proxies and network connectivity to the repository hosting the provider jar
4. Inspect the cause chain (BootstrapMavenException) for the exact repository/HTTP error

Example fix

// before (broken coordinates in registry client config)
{"id":"my-registry","client-factory-provider":"com.example:factory-provider:9.9.9"}
// after (valid released coordinates)
{"id":"my-registry","client-factory-provider":"com.example:factory-provider:1.0.0"}

// Verify resolvability beforehand
new DefaultArtifact(groupId, artifactId, classifier, type, version);
mvn dependency:get -Dartifact=groupId:artifactId:version

try { resolver.getClientFactory(); } catch (IllegalStateException e) { if (e.getCause() instanceof BootstrapMavenException bme) { /* log bme, fix coordinates/repo access */ } throw e; }

When it happens

Trigger: Calling ExtensionCatalogResolver.getClientFactory() when a registry client config has a providerArtifact and artifactResolver.resolve(DefaultArtifact...) throws BootstrapMavenException (artifact missing from all configured repositories, bad coordinates, or repository access failure).

Common situations: Typo in groupId/artifactId/version of the registry client factory provider in the Maven settings or registry client config JSON; provider artifact removed or version bumped upstream; corporate proxy/firewall blocking repository access; repository not declared in settings.xml.

Related errors

• Specifying a stream requires the Quarkus extension registry
• This goal requires a Quarkus extension registry client to be
• Failed to resolve artifact ${artifact}
• Failed to resolve
• Failed to resolve artifact ${artifact}

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