eclipse-vertx/vert.x · error · IllegalStateException

No ClusterManagerFactory instances found on classpath

Error message

No ClusterManagerFactory instances found on classpath

What it means

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.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/impl/VertxBootstrapImpl.java:275

      fileResolver,
      threadFactory,
      executorServiceFactory,
      eventExecutorProvider,
      enableShadowContext);
  }

  public Vertx vertx() {
    VertxImpl vertx = instantiateVertx(null, null);
    vertx.init(verticleFactories);
    return vertx;
  }

  /**
   * Build and return the clustered vertx instance
   */
  public Future<Vertx> clusteredVertx() {
    if (clusterManager == null) {
      throw new IllegalStateException("No ClusterManagerFactory instances found on classpath");
    }
    NodeSelector nodeSelector = clusterNodeSelector;
    if (nodeSelector == null) {
      nodeSelector = new DefaultNodeSelector();
    }
    VertxImpl vertx = instantiateVertx(clusterManager, nodeSelector);
    return vertx.initClustered(options, verticleFactories);
  }

  /**
   * @return the verticle factories to use
   */
  public List<VerticleFactory> verticleFactories() {
    return verticleFactories;
  }

  /**
   * Set the list of {@code VerticleFactory} to use.

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Add a clustering provider dependency, e.g. io.vertx:vertx-hazelcast (matching your Vert.x version)
2. Or explicitly set one: Vertx.builder().withClusterManager(new HazelcastClusterManager())
3. Verify META-INF/services/io.vertx.core.spi.cluster.ClusterManagerFactory exists in the built jar (fix shade mergeServiceFiles / ServicesResourceTransformer)
4. If modular, add `provides io.vertx.core.spi.cluster.ClusterManagerFactory with ...` to module-info

Example fix

// before
Vertx vertx = Vertx.builder().buildClustered().toBlocking().value(); // no provider on classpath
// after
Vertx vertx = Vertx.builder()
    .withClusterManager(new HazelcastClusterManager())
    .buildClustered().toBlocking().value();

if (ServiceLoader.load(ClusterManagerFactory.class).iterator().hasNext() == false) {
  throw new IllegalStateException("Add a clustering provider (vertx-hazelcast/vertx-zookeeper/vertx-infinispan) to the classpath");
}

try { vertx = Vertx.builder().buildClustered(); } catch (IllegalStateException e) { if (e.getMessage().contains("ClusterManagerFactory")) log.error("Missing clustering provider jar"); throw e; }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• Cannot find META-INF/services/${clazz} on classpath
• Cannot find service on the classpath or module path
• Nesting more than two levels is not supported
• Cannot find vertx-version.txt on classpath
• ${packageFolderURL} is not a JAR file

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/75c5fdbc819f40ae. Report an issue: GitHub.