{"record":{"id":"75c5fdbc819f40ae","repo":"eclipse-vertx/vert.x","slug":"no-clustermanagerfactory-instances-found-on-classp","errorCode":null,"errorMessage":"No ClusterManagerFactory instances found on classpath","messagePattern":"No ClusterManagerFactory instances found on classpath","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/impl/VertxBootstrapImpl.java","lineNumber":275,"sourceCode":"      fileResolver,\n      threadFactory,\n      executorServiceFactory,\n      eventExecutorProvider,\n      enableShadowContext);\n  }\n\n  public Vertx vertx() {\n    VertxImpl vertx = instantiateVertx(null, null);\n    vertx.init(verticleFactories);\n    return vertx;\n  }\n\n  /**\n   * Build and return the clustered vertx instance\n   */\n  public Future<Vertx> clusteredVertx() {\n    if (clusterManager == null) {\n      throw new IllegalStateException(\"No ClusterManagerFactory instances found on classpath\");\n    }\n    NodeSelector nodeSelector = clusterNodeSelector;\n    if (nodeSelector == null) {\n      nodeSelector = new DefaultNodeSelector();\n    }\n    VertxImpl vertx = instantiateVertx(clusterManager, nodeSelector);\n    return vertx.initClustered(options, verticleFactories);\n  }\n\n  /**\n   * @return the verticle factories to use\n   */\n  public List<VerticleFactory> verticleFactories() {\n    return verticleFactories;\n  }\n\n  /**\n   * Set the list of {@code VerticleFactory} to use.","sourceCodeStart":257,"sourceCodeEnd":293,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/impl/VertxBootstrapImpl.java#L257-L293","documentation":"VertxBootstrapImpl.clusteredVertx() requires a ClusterManagerFactory resolved from the classpath. When none is found (clusterManager == null) it throws IllegalStateException('No ClusterManagerFactory instances found on classpath') because clustered Vert.x cannot form a cluster without one.","triggerScenarios":"Calling Vertx.builder().clustered() / buildClustered() (or Vertx.clusteredVertx) without a clustering SPI provider jar such as vertx-hazelcast, vertx-zookeeper, or vertx-infinispan on the runtime classpath/module path.","commonSituations":"Adding only vertx-core and requesting clustered mode; fat-jar shading that dropped META-INF/services entries; JPMS module without provides ClusterManagerFactory clause; setting an explicit clusterManager that failed to load earlier leaving factory null.","solutions":["Add a clustering provider dependency, e.g. io.vertx:vertx-hazelcast (matching your Vert.x version)","Or explicitly set one: Vertx.builder().withClusterManager(new HazelcastClusterManager())","Verify META-INF/services/io.vertx.core.spi.cluster.ClusterManagerFactory exists in the built jar (fix shade mergeServiceFiles / ServicesResourceTransformer)","If modular, add `provides io.vertx.core.spi.cluster.ClusterManagerFactory with ...` to module-info"],"exampleFix":"// before\nVertx vertx = Vertx.builder().buildClustered().toBlocking().value(); // no provider on classpath\n// after\nVertx vertx = Vertx.builder()\n    .withClusterManager(new HazelcastClusterManager())\n    .buildClustered().toBlocking().value();","handlingStrategy":"validation","validationCode":"if (ServiceLoader.load(ClusterManagerFactory.class).iterator().hasNext() == false) {\n  throw new IllegalStateException(\"Add a clustering provider (vertx-hazelcast/vertx-zookeeper/vertx-infinispan) to the classpath\");\n}","typeGuard":null,"tryCatchPattern":"try { vertx = Vertx.builder().buildClustered(); } catch (IllegalStateException e) { if (e.getMessage().contains(\"ClusterManagerFactory\")) log.error(\"Missing clustering provider jar\"); throw e; }","preventionTips":["Declare clustering provider dependency explicitly in build files","Or pass an explicit ClusterManager to Vertx.builder().withClusterManager(...)","Verify shaded jars keep META-INF/services entries","Keep provider version aligned with vertx-core version"],"tags":["clustering","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-14T05:17:10.506Z"}