quarkusio/quarkus · error · IllegalStateException

Failed to load registry client factory from ${url}

Error message

Failed to load registry client factory from ${url}

What it means

Thrown as IllegalStateException when loading the registry client factory from a URL fails. loadFromUrl creates a classloader over the provider jar, locates the RegistryClientFactory service provider, instantiates it and calls newRegistryClientFactory(getClientEnv()); any Exception in that sequence (missing ServiceLoader entry, class incompatibility, provider constructor/env failure) is wrapped.

Source

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

                final Iterator<RegistryClientFactoryProvider> i = ServiceLoader
                        .load(RegistryClientFactoryProvider.class, providerCl).iterator();
                if (!i.hasNext()) {
                    throw new Exception("Failed to locate an implementation of " + RegistryClientFactoryProvider.class.getName()
                            + " service provider");
                }
                final RegistryClientFactoryProvider provider = i.next();
                if (i.hasNext()) {
                    final StringBuilder buf = new StringBuilder();
                    buf.append("Found more than one registry client factory provider ")
                            .append(provider.getClass().getName());
                    while (i.hasNext()) {
                        buf.append(", ").append(i.next().getClass().getName());
                    }
                    throw new Exception(buf.toString());
                }
                return provider.newRegistryClientFactory(getClientEnv());
            } catch (Exception e) {
                throw new IllegalStateException("Failed to load registry client factory from " + url, e);
            }
        }

        private RegistryClientFactory getDefaultClientFactory() {
            return defaultClientFactory == null ? defaultClientFactory = new MavenRegistryClientFactory(artifactResolver, log)
                    : defaultClientFactory;
        }

        private RegistryClientEnvironment getClientEnv() {
            return clientEnv == null ? clientEnv = new RegistryClientEnvironment() {

                @Override
                public MessageWriter log() {
                    return log;
                }

                @Override
                public MavenArtifactResolver resolver() {

View on GitHub (pinned to e1c734241f)

Solutions

  1. Verify the provider jar contains META-INF/services/io.quarkus.registry.RegistryClientFactory with a valid implementation class
  2. Rebuild/republish the provider jar against the registry-client version in use
  3. Read the cause (Exception) message: zero or multiple providers are reported with the class names found
  4. Align the registry-client and provider jar versions

Example fix

// before: provider jar missing service registration
src/main/resources/META-INF/services/io.quarkus.registry.RegistryClientFactory (absent)
// after
src/main/resources/META-INF/services/io.quarkus.registry.RegistryClientFactory -> com.example.MyRegistryClientFactory
Defensive patterns

Strategy: try-catch

Validate before calling

// Check provider jar structure before loading
try (JarFile jf = new JarFile(providerJar)) {
  boolean ok = jf.getEntry("META-INF/services/io.quarkus.registry.RegistryClientFactory") != null;
}

Try / catch

try { resolver.getClientFactory(); } catch (IllegalStateException e) { log.error("Registry client factory load failed: " + e.getCause(), e); throw e; }

Prevention

When it happens

Trigger: getClientFactory() -> loadFromArtifact -> loadFromUrl when the provider jar does not contain a valid META-INF/services RegistryClientFactory registration, the provider class fails to instantiate, multiple/zero providers are found (the StringBuilder branch aggregating provider names), or newRegistryClientFactory throws.

Common situations: Provider jar built against an incompatible RegistryClientFactory API version; jar missing the service descriptor file; shaded jar stripping META-INF/services; classloader conflicts with different Quarkus registry-client versions.

Related errors

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