{"record":{"id":"6f146c322907158d","repo":"eclipse-vertx/vert.x","slug":"can-t-get-cluster-wide-map-if-not-clustered","errorCode":null,"errorMessage":"Can't get cluster wide map if not clustered","messagePattern":"Can't get cluster wide map if not clustered","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/shareddata/impl/SharedDataImpl.java","lineNumber":54,"sourceCode":"\n  private final VertxInternal vertx;\n  private final ClusterManager clusterManager;\n  private final LocalAsyncLocks localAsyncLocks;\n  private final ConcurrentMap<String, LocalAsyncMapImpl<?, ?>> localAsyncMaps = new ConcurrentHashMap<>();\n  private final ConcurrentMap<String, Counter> localCounters = new ConcurrentHashMap<>();\n  private final ConcurrentMap<String, LocalMap<?, ?>> localMaps = new ConcurrentHashMap<>();\n\n  public SharedDataImpl(VertxInternal vertx, ClusterManager clusterManager) {\n    this.vertx = vertx;\n    this.clusterManager = clusterManager;\n    localAsyncLocks = new LocalAsyncLocks();\n  }\n\n  @Override\n  public <K, V> Future<AsyncMap<K, V>> getClusterWideMap(String name) {\n    Objects.requireNonNull(name, \"name\");\n    if (clusterManager == null) {\n      throw new IllegalStateException(\"Can't get cluster wide map if not clustered\");\n    }\n    Promise<AsyncMap<K, V>> promise = vertx.promise();\n    clusterManager.getAsyncMap(name, promise);\n    return promise.future().map(WrappedAsyncMap::new);\n  }\n\n  @Override\n  public <K, V> Future<AsyncMap<K, V>> getAsyncMap(String name) {\n    Objects.requireNonNull(name, \"name\");\n    if (clusterManager == null) {\n      return getLocalAsyncMap(name);\n    } else {\n      Promise<AsyncMap<K, V>> promise = vertx.promise();\n      clusterManager.getAsyncMap(name, promise);\n      return promise.future().map(WrappedAsyncMap::new);\n    }\n  }\n","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/shareddata/impl/SharedDataImpl.java#L36-L72","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Start Vert.x clustered: use Vertx.builder().withClusterManager(new HazelcastClusterManager()).buildClustered() (or your chosen manager).","If single-node, use getLocalMap / getAsyncMap (LocalAsyncMap) instead of cluster-wide APIs.","Guard with vertx.isClustered() (or check your deployment mode) before calling cluster-wide SharedData APIs.","Verify the cluster manager dependency and configuration (cluster.xml etc.) are present."],"exampleFix":"// before\nvertx.sharedData().getClusterWideMap(\"mymap\"); // IllegalStateException when not clustered\n// after\nif (!vertx.isClustered()) {\n  AsyncMap<K,V> map = ... local variant ...\n} else {\n  vertx.sharedData().getClusterWideMap(\"mymap\");\n}","handlingStrategy":"validation","validationCode":"if (!vertx.isClustered()) {\n  throw new IllegalStateException(\"cluster wide map requires a clustered Vertx instance\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  vertx.sharedData().getClusterWideMap(\"mymap\");\n} catch (IllegalStateException e) {\n  if (e.getMessage().contains(\"not clustered\")) {\n    // fall back to local map / abort\n  } else throw e;\n}","preventionTips":["Only call cluster-wide SharedData APIs on instances built via buildClustered().","In shared libraries, take the AsyncMap provider as a parameter instead of assuming clustering.","Add a startup assertion that clustering is enabled in clustered deployments.","Check that the cluster manager dependency and config are on the classpath."],"tags":["shared-data","clustering","illegal-state","async-map"],"backgroundTag":"feature-not-enabled","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"}