SonarSource/sonarqube · error · MessageException

This node has a cluster name [%s], which does not match [%s]

Error message

This node has a cluster name [%s], which does not match [%s] from the cluster

What it means

registerClusterName stores the cluster name in a Hazelcast atomic reference; the first node wins and every other node must present the identical name. A node whose configured cluster name differs from the cluster's registered value is rejected with a MessageException, since differently named nodes must not join the same Hazelcast cluster.

Source

Thrown at server/sonar-main/src/main/java/org/sonar/application/cluster/ClusterAppStateImpl.java:178

    if (!wasSet) {
      String clusterVersion = sqVersion.get();
      if (!sqVersion.get().equals(sonarqubeVersion)) {
        throw new IllegalStateException(
          format("The local version %s is not the same as the cluster %s", sonarqubeVersion, clusterVersion));
      }
    }
  }

  @Override
  public void registerClusterName(String clusterName) {
    DistributedReference<String> property = hzMember.getAtomicReference(CLUSTER_NAME);
    boolean wasSet = property.compareAndSet(null, clusterName);

    if (!wasSet) {
      String clusterValue = property.get();
      if (!property.get().equals(clusterName)) {
        throw new MessageException(
          format("This node has a cluster name [%s], which does not match [%s] from the cluster", clusterName, clusterValue));
      }
    }
  }

  @Override
  public Optional<String> getLeaderHostName() {
    UUID leaderUuid = (UUID) hzMember.getAtomicReference(LEADER).get();
    if (leaderUuid != null) {
      Optional<Member> leader = hzMember.getCluster().getMembers().stream().filter(m -> m.getUuid().equals(leaderUuid)).findFirst();
      if (leader.isPresent()) {
        return Optional.of(leader.get().getAddress().getHost());
      }
    }
    return Optional.empty();
  }

  @Override

View on GitHub (pinned to 184c821202)

Solutions

Set sonar.cluster.name on the failing node to exactly match the value used by the other cluster members
Compare the configured name with the cluster name logged by healthy members (watch for case/whitespace differences)
Regenerate the node configuration from the current cluster's reference configuration
Ensure load balancer and Hazelcast discovery configs reference one single consistent cluster name

Example fix

// before (node conf/sonar.properties)
sonar.cluster.name=prod-sonarqube-cluster
// after (match existing members)
sonar.cluster.name=production-sonar

Defensive patterns

Strategy: validation

Validate before calling

String myName = props.getProperty("sonar.cluster.name");
if (myName == null || myName.trim().isEmpty() || !myName.equals(EXPECTED_CLUSTER_NAME)) {
  throw new IllegalArgumentException("sonar.cluster.name mismatch: " + myName);
}

Try / catch

try {
  node.start();
} catch (MessageException e) {
  if (e.getMessage().contains("does not match")) {
    log.error("Cluster name mismatch: fix sonar.cluster.name to match other members", e);
  }
}

Prevention

Keep sonar.cluster.name identical across all nodes (no trailing whitespace)
Template cluster configs from a single source of truth
Diff new node configs against a healthy member before joining

When it happens

Trigger: Starting a node whose sonar.cluster.name (clusterName parameter) does not equal the name already registered by other members — usually a copy-pasted or stale configuration on one node.

Common situations: Cloning configuration between environments and forgetting to change sonar.cluster.name, typos or trailing whitespace in one node's config, or adding a new node copied from an old template.

Related errors

AI-assisted analysis of SonarSource/sonarqube@184c821202 (2026-09-09). Data as JSON: /api/errors/2b323e3d25490d6e. Report an issue: GitHub.