{"record":{"id":"4253a72441baebcc","repo":"eclipse-vertx/vert.x","slug":"cannot-find-meta-inf-services-clazz-on-classpat","errorCode":null,"errorMessage":"Cannot find META-INF/services/${clazz} on classpath","messagePattern":"Cannot find META-INF/services/(.+?) on classpath","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/impl/ServiceHelper.java","lineNumber":27,"sourceCode":" * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0\n */\n\npackage io.vertx.core.impl;\n\nimport java.util.*;\n\n/**\n * A helper class for loading factories from the classpath.\n *\n * @author <a href=\"http://tfox.org\">Tim Fox</a>\n */\npublic class ServiceHelper {\n\n  @Deprecated\n  public static <T> T loadFactory(Class<T> clazz) {\n    T factory = loadFactoryOrNull(clazz);\n    if (factory == null) {\n      throw new IllegalStateException(\"Cannot find META-INF/services/\" + clazz.getName() + \" on classpath\");\n    }\n    return factory;\n  }\n\n  @Deprecated\n  public static <T> T loadFactoryOrNull(Class<T> clazz) {\n    Collection<T> collection = loadFactories(clazz);\n    if (!collection.isEmpty()) {\n      return collection.iterator().next();\n    } else {\n      return null;\n    }\n  }\n\n  @Deprecated\n  public static <T> List<T> loadFactories(Class<T> clazz) {\n    return loadFactories(clazz, null);\n  }","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/impl/ServiceHelper.java#L9-L45","documentation":"Deprecated ServiceHelper.loadFactory(Class) uses the old ServiceLoader file lookup; if no implementation of clazz is registered under META-INF/services/<class name>, IllegalStateException('Cannot find META-INF/services/<clazz> on classpath') is thrown. It signals a required SPI implementation is missing from the runtime classpath.","triggerScenarios":"Calling loadFactory(SomeSpi.class) (or Vert.x internals resolving e.g. ClusterManagerFactory, LogDelegateFactory, DNS resolver providers) when no provider file exists on the classpath.","commonSituations":"Building an uber-jar that strips META-INF/services entries; forgetting to add the provider implementation dependency (e.g. vertx-clustering-implementations) at runtime; packaging as JPMS module without 'provides' clauses.","solutions":["Add the dependency that provides the SPI implementation (e.g. io.vertx:vertx-hazelcast for clustering)","Ensure your build/shading tool merges META-INF/services files (ServicesResourceTransformer for shade, mergeServiceFiles for Gradle)","If on JPMS, add a provides ... with ... clause in module-info","Migrate to the non-deprecated overload taking a ServiceLoader or ServiceHelper.loadFactoryOrNull with a fallback"],"exampleFix":"// before\nClusterManager cm = ServiceHelper.loadFactory(ClusterManagerFactory.class).newManager();\n// after\nClusterManager cm = Optional.ofNullable(ServiceHelper.loadFactoryOrNull(ClusterManagerFactory.class))\n    .map(ClusterManagerFactory::newManager)\n    .orElseGet(HazelcastClusterManager::new);","handlingStrategy":"fallback","validationCode":"ClusterManagerFactory f = ServiceHelper.loadFactoryOrNull(ClusterManagerFactory.class);\nif (f == null) throw new IllegalStateException(\"Add the clustering provider jar to the classpath\");","typeGuard":null,"tryCatchPattern":"try { factory = ServiceHelper.loadFactory(Spi.class); } catch (IllegalStateException e) { log.error(\"Missing SPI provider: add the implementation jar (check META-INF/services)\"); throw e; }","preventionTips":["Include provider jars (e.g. vertx-hazelcast) in runtime deployment artifacts","Configure shade plugin ServicesResourceTransformer / mergeServiceFiles","Smoke-test the built jar in a clean environment","Prefer explicit dependency injection of the factory over ServiceHelper when possible"],"tags":["service-loader","classpath","spi","missing-dependency"],"backgroundTag":"missing-optional-dependency","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}