eclipse-vertx/vert.x · error · IllegalStateException

Can't get cluster wide map if not clustered

Error message

Can't get cluster wide map if not clustered

What it means

getClusterWideMap returns an AsyncMap backed by the cluster manager (Hazelcast, Infinispan, ZooKeeper, Redis). When Vert.x was created without clustering, there is no cluster manager and the method throws IllegalStateException immediately.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/shareddata/impl/SharedDataImpl.java:54

  private final VertxInternal vertx;
  private final ClusterManager clusterManager;
  private final LocalAsyncLocks localAsyncLocks;
  private final ConcurrentMap<String, LocalAsyncMapImpl<?, ?>> localAsyncMaps = new ConcurrentHashMap<>();
  private final ConcurrentMap<String, Counter> localCounters = new ConcurrentHashMap<>();
  private final ConcurrentMap<String, LocalMap<?, ?>> localMaps = new ConcurrentHashMap<>();

  public SharedDataImpl(VertxInternal vertx, ClusterManager clusterManager) {
    this.vertx = vertx;
    this.clusterManager = clusterManager;
    localAsyncLocks = new LocalAsyncLocks();
  }

  @Override
  public <K, V> Future<AsyncMap<K, V>> getClusterWideMap(String name) {
    Objects.requireNonNull(name, "name");
    if (clusterManager == null) {
      throw new IllegalStateException("Can't get cluster wide map if not clustered");
    }
    Promise<AsyncMap<K, V>> promise = vertx.promise();
    clusterManager.getAsyncMap(name, promise);
    return promise.future().map(WrappedAsyncMap::new);
  }

  @Override
  public <K, V> Future<AsyncMap<K, V>> getAsyncMap(String name) {
    Objects.requireNonNull(name, "name");
    if (clusterManager == null) {
      return getLocalAsyncMap(name);
    } else {
      Promise<AsyncMap<K, V>> promise = vertx.promise();
      clusterManager.getAsyncMap(name, promise);
      return promise.future().map(WrappedAsyncMap::new);
    }
  }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Start Vert.x clustered: use Vertx.builder().withClusterManager(new HazelcastClusterManager()).buildClustered() (or your chosen manager).
2. If single-node, use getLocalMap / getAsyncMap (LocalAsyncMap) instead of cluster-wide APIs.
3. Guard with vertx.isClustered() (or check your deployment mode) before calling cluster-wide SharedData APIs.
4. Verify the cluster manager dependency and configuration (cluster.xml etc.) are present.

Example fix

// before
vertx.sharedData().getClusterWideMap("mymap"); // IllegalStateException when not clustered
// after
if (!vertx.isClustered()) {
  AsyncMap<K,V> map = ... local variant ...
} else {
  vertx.sharedData().getClusterWideMap("mymap");
}

if (!vertx.isClustered()) {
  throw new IllegalStateException("cluster wide map requires a clustered Vertx instance");
}

try {
  vertx.sharedData().getClusterWideMap("mymap");
} catch (IllegalStateException e) {
  if (e.getMessage().contains("not clustered")) {
    // fall back to local map / abort
  } else throw e;
}

When it happens

Trigger: Calling SharedData.getClusterWideMap(name) (or getLocks/getCounter of cluster-wide scope) on a Vertx instance built with Vertx.vertx() instead of a clustered Vertx (Vertx.builder().withClusterManager(...).buildClustered() / starter).

Common situations: Running the app in single-node dev mode while code assumes a clustered deployment; vertx.cluster.manager classpath dep missing so clustering silently disabled; forgetting to await clustered startup before using SharedData.

Related errors

• ttl must be positive: ${ttl}
• Cannot put null in key or value of async map
• Invalid type: ${obj.getClass().getName()} to put in async ma
• Already a codec registered with name
• Already a default codec registered for class

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