{"record":{"id":"38515fa9f9ff0e8e","repo":"quarkusio/quarkus","slug":"failed-to-load-registry-client-factory-from-url","errorCode":null,"errorMessage":"Failed to load registry client factory from ${url}","messagePattern":"Failed to load registry client factory from (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/ExtensionCatalogResolver.java","lineNumber":197,"sourceCode":"                final Iterator<RegistryClientFactoryProvider> i = ServiceLoader\n                        .load(RegistryClientFactoryProvider.class, providerCl).iterator();\n                if (!i.hasNext()) {\n                    throw new Exception(\"Failed to locate an implementation of \" + RegistryClientFactoryProvider.class.getName()\n                            + \" service provider\");\n                }\n                final RegistryClientFactoryProvider provider = i.next();\n                if (i.hasNext()) {\n                    final StringBuilder buf = new StringBuilder();\n                    buf.append(\"Found more than one registry client factory provider \")\n                            .append(provider.getClass().getName());\n                    while (i.hasNext()) {\n                        buf.append(\", \").append(i.next().getClass().getName());\n                    }\n                    throw new Exception(buf.toString());\n                }\n                return provider.newRegistryClientFactory(getClientEnv());\n            } catch (Exception e) {\n                throw new IllegalStateException(\"Failed to load registry client factory from \" + url, e);\n            }\n        }\n\n        private RegistryClientFactory getDefaultClientFactory() {\n            return defaultClientFactory == null ? defaultClientFactory = new MavenRegistryClientFactory(artifactResolver, log)\n                    : defaultClientFactory;\n        }\n\n        private RegistryClientEnvironment getClientEnv() {\n            return clientEnv == null ? clientEnv = new RegistryClientEnvironment() {\n\n                @Override\n                public MessageWriter log() {\n                    return log;\n                }\n\n                @Override\n                public MavenArtifactResolver resolver() {","sourceCodeStart":179,"sourceCodeEnd":215,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/ExtensionCatalogResolver.java#L179-L215","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the provider jar contains META-INF/services/io.quarkus.registry.RegistryClientFactory with a valid implementation class","Rebuild/republish the provider jar against the registry-client version in use","Read the cause (Exception) message: zero or multiple providers are reported with the class names found","Align the registry-client and provider jar versions"],"exampleFix":"// before: provider jar missing service registration\nsrc/main/resources/META-INF/services/io.quarkus.registry.RegistryClientFactory (absent)\n// after\nsrc/main/resources/META-INF/services/io.quarkus.registry.RegistryClientFactory -> com.example.MyRegistryClientFactory","handlingStrategy":"try-catch","validationCode":"// Check provider jar structure before loading\ntry (JarFile jf = new JarFile(providerJar)) {\n  boolean ok = jf.getEntry(\"META-INF/services/io.quarkus.registry.RegistryClientFactory\") != null;\n}","typeGuard":null,"tryCatchPattern":"try { resolver.getClientFactory(); } catch (IllegalStateException e) { log.error(\"Registry client factory load failed: \" + e.getCause(), e); throw e; }","preventionTips":["Ensure provider jars include the META-INF/services descriptor (check shading filters)","Build the provider against the same registry-client version used at runtime","Test provider jar loading in isolation before deploying","Keep registry-client and provider versions aligned"],"tags":["classpath","serviceloader","registry-client"],"backgroundTag":"service-provider-load-failed","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}