SonarSource/sonarqube · critical

The local version %s is not the same as the cluster %s

Error message

The local version %s is not the same as the cluster %s

What it means

When a cluster node registers its SonarQube version, the first member sets the version in a Hazelcast atomic reference; later members must match it. If the reference is already set and the local version differs from the cluster value, registration fails with IllegalStateException, because mixed-version cluster members are not supported.

Source

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

  private void tryToReleaseWebLeaderLock(UUID uuidOfLeader) {
    DistributedReference<UUID> leader = hzMember.getAtomicReference(LEADER);
    leader.compareAndSet(uuidOfLeader, null);
  }

  @Override
  public void reset() {
    throw new IllegalStateException("state reset is not supported in cluster mode");
  }

  @Override
  public void registerSonarQubeVersion(String sonarqubeVersion) {
    DistributedReference<String> sqVersion = hzMember.getAtomicReference(SONARQUBE_VERSION);
    boolean wasSet = sqVersion.compareAndSet(null, sonarqubeVersion);

    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));
      }
    }
  }

View on GitHub (pinned to 184c821202)

Solutions

  1. Upgrade or downgrade the node so its SonarQube version exactly matches the rest of the cluster
  2. Pin all cluster members to the same release (same Docker tag / same artifact) before restarting
  3. Follow the official rolling-upgrade sequence: upgrade, restart and verify all nodes one at a time with identical versions
  4. Check the currently registered cluster version in logs and align the failing node's deployment to it

Example fix

// before (docker-compose, mixed tags)
image: sonarqube:9.9-community  # node A
image: sonarqube:10.3-community # node B -> error
// after
image: sonarqube:10.3-community # all nodes identical
Defensive patterns

Strategy: validation

Validate before calling

String expected = "10.3";
String running = detectDeployedSonarVersion(); // from image/artifact metadata
if (!expected.equals(running)) {
  throw new IllegalStateException("node version " + running + " != cluster version " + expected);
}

Try / catch

try {
  node.start();
} catch (IllegalStateException e) {
  if (e.getMessage().startsWith("The local version")) {
    log.error("Version mismatch in cluster; align all nodes to the same release", e);
  }
}

Prevention

When it happens

Trigger: Starting a node with a different sonarqubeVersion than the one already registered by other cluster members, typically while a rolling upgrade is in progress or one node was not upgraded.

Common situations: Rolling upgrades where some members still run the old SonarQube version, nodes pulled from different Docker image tags in the same cluster, or a node restarting against a cluster upgraded while it was down.

Related errors

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