SonarSource/sonarqube · error

state reset is not supported in cluster mode

Error message

state reset is not supported in cluster mode

What it means

ClusterAppStateImpl.reset() explicitly refuses to run when the node operates in cluster mode: state (leader, version, cluster name) lives in Hazelcast distributed references and cannot be wiped on a single member. Calling reset on a cluster-mode node is an unsupported operation by design.

Source

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

  @Override
  public void tryToReleaseWebLeaderLock() {
    tryToReleaseWebLeaderLock(hzMember.getUuid());
  }

  /**
   * Tries to release the lock of the cluster leader. It is safe to call this method even if one is not sure about the UUID of the leader.
   * If all nodes call this method then we can be confident that the lock is released.
   *
   * @param uuidOfLeader - the UUID of the leader to release the lock. In case the UUID is not the leader's uuid this method has no effect.
   */
  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) {

View on GitHub (pinned to 184c821202)

Solutions

1. Do not call reset() on cluster-mode nodes; restart the individual node instead
2. Clear distributed state by shutting down and rejoining the cluster member (Hazelcast state is rebuilt on join)
3. Only use reset() with the standalone AppState (non-cluster ProcessLauncher deployment)
4. Refactor calling code to branch on cluster vs standalone mode before attempting a reset

Example fix

// before
appState.reset();
// after
if (appState instanceof ClusterAppStateImpl) {
  throw new UnsupportedOperationException("restart the node instead of resetting state in cluster mode");
}
appState.reset();

boolean isClusterMode = Boolean.parseBoolean(System.getProperty("sonar.cluster.enabled", "false"));
if (isClusterMode) {
  // skip reset(); restart the node instead
}

if (appState instanceof ClusterAppStateImpl) { /* reset not supported */ }

try {
  appState.reset();
} catch (IllegalStateException e) {
  if (e.getMessage().contains("state reset is not supported in cluster mode")) {
    log.warn("Restart the cluster node instead of resetting state");
  }
}

When it happens

Trigger: Calling reset() on a ClusterAppStateImpl instance backed by a Hazelcast member instead of the standalone (monolith) app state, e.g. via code paths or tests that reset process state on a cluster node.

Common situations: Administrative scripts or lifecycle hooks that call app state reset for standalone restarts being reused against a Search/Web/CE node joined to a cluster; running the same operational tooling against both standalone and clustered deployments.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Restart is not possible with cluster mode
• The local version %s is not the same as the cluster %s
• This node has a cluster name [%s], which does not match [%s]
• Unsupported in cluster mode
• %s is not a valid url

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