SonarSource/sonarqube · error

Restart is not possible with cluster mode

Error message

Restart is not possible with cluster mode

What it means

AppReloaderImpl.reload implements in-place restart (e.g. from the web UI 'Restart' action) by reloading settings and resetting the filesystem. Cluster mode is unsupported for this because restarting only the app node would break cluster coordination, so reload() throws this IllegalStateException up front when ClusterSettings.isClusterEnabled(settings) is true.

Source

Thrown at server/sonar-main/src/main/java/org/sonar/application/AppReloaderImpl.java:54

public class AppReloaderImpl implements AppReloader {

  private final AppSettingsLoader settingsLoader;
  private final FileSystem fileSystem;
  private final AppState appState;
  private final AppLogging logging;

  public AppReloaderImpl(AppSettingsLoader settingsLoader, FileSystem fileSystem, AppState appState, AppLogging logging) {
    this.settingsLoader = settingsLoader;
    this.fileSystem = fileSystem;
    this.appState = appState;
    this.logging = logging;
  }

  @Override
  public void reload(AppSettings settings) throws IOException {
    if (ClusterSettings.isClusterEnabled(settings)) {
      throw new IllegalStateException("Restart is not possible with cluster mode");
    }
    AppSettings reloaded = settingsLoader.load();
    ensureUnchangedConfiguration(settings.getProps(), reloaded.getProps());
    settings.reload(reloaded.getProps());

    fileSystem.reset();
    logging.configure();
    appState.reset();
  }

  private static void ensureUnchangedConfiguration(Props oldProps, Props newProps) {
    verifyUnchanged(oldProps, newProps, PATH_DATA.getKey());
    verifyUnchanged(oldProps, newProps, PATH_WEB.getKey());
    verifyUnchanged(oldProps, newProps, PATH_LOGS.getKey());
    verifyUnchanged(oldProps, newProps, PATH_TEMP.getKey());
    verifyUnchanged(oldProps, newProps, CLUSTER_ENABLED.getKey());
  }

View on GitHub (pinned to 184c821202)

Solutions

1. Restart each cluster node via the OS service manager or orchestrator instead of the in-app restart (e.g. systemctl restart sonarqube).
2. Use the cluster's documented restart/rolling-upgrade procedure for Data Center Edition.
3. If restart is genuinely needed in-app, run in standalone mode (sonar.cluster.enabled=false).
4. Automate cluster restarts through the deployment tooling rather than the restart endpoint.

Example fix

// before
curl -X POST http://localhost:9000/api/system/restart  // fails on cluster
// after
sudo systemctl restart sonarqube  # per node, orchestrated

boolean cluster = Boolean.parseBoolean(props.getOrDefault("sonar.cluster.enabled", "false"));
if (cluster) {
    throw new UnsupportedOperationException("Use OS service restart per node, not /api/system/restart");
}

try { reloader.reload(settings); } catch (IllegalStateException e) { log.warning("In-place restart unavailable: " + e.getMessage()); }

When it happens

Trigger: Invoking the server restart/reload operation (web UI restart button or RestartHTTPAction) while sonar.cluster.enabled=true in the configuration.

Common situations: Administrators clicking Restart in a SonarQube Data Center / clustered deployment; automation scripts calling the restart endpoint on cluster nodes; forgetting that clustered setups must restart via the process manager/systemd on every node.

Related errors

• state reset is not supported in cluster mode
• Restart not allowed for cluster nodes
• Property [%s] cannot be changed on restart: [%s] => [%s]
• The local version %s is not the same as the cluster %s
• This node has a cluster name [%s], which does not match [%s]

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