{"record":{"id":"2410e6c1f39ecdd9","repo":"SonarSource/sonarqube","slug":"restart-is-not-possible-with-cluster-mode","errorCode":null,"errorMessage":"Restart is not possible with cluster mode","messagePattern":"Restart is not possible with cluster mode","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/sonar-main/src/main/java/org/sonar/application/AppReloaderImpl.java","lineNumber":54,"sourceCode":"\npublic class AppReloaderImpl implements AppReloader {\n\n  private final AppSettingsLoader settingsLoader;\n  private final FileSystem fileSystem;\n  private final AppState appState;\n  private final AppLogging logging;\n\n  public AppReloaderImpl(AppSettingsLoader settingsLoader, FileSystem fileSystem, AppState appState, AppLogging logging) {\n    this.settingsLoader = settingsLoader;\n    this.fileSystem = fileSystem;\n    this.appState = appState;\n    this.logging = logging;\n  }\n\n  @Override\n  public void reload(AppSettings settings) throws IOException {\n    if (ClusterSettings.isClusterEnabled(settings)) {\n      throw new IllegalStateException(\"Restart is not possible with cluster mode\");\n    }\n    AppSettings reloaded = settingsLoader.load();\n    ensureUnchangedConfiguration(settings.getProps(), reloaded.getProps());\n    settings.reload(reloaded.getProps());\n\n    fileSystem.reset();\n    logging.configure();\n    appState.reset();\n  }\n\n  private static void ensureUnchangedConfiguration(Props oldProps, Props newProps) {\n    verifyUnchanged(oldProps, newProps, PATH_DATA.getKey());\n    verifyUnchanged(oldProps, newProps, PATH_WEB.getKey());\n    verifyUnchanged(oldProps, newProps, PATH_LOGS.getKey());\n    verifyUnchanged(oldProps, newProps, PATH_TEMP.getKey());\n    verifyUnchanged(oldProps, newProps, CLUSTER_ENABLED.getKey());\n  }\n","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-main/src/main/java/org/sonar/application/AppReloaderImpl.java#L36-L72","documentation":"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.","triggerScenarios":"Invoking the server restart/reload operation (web UI restart button or RestartHTTPAction) while sonar.cluster.enabled=true in the configuration.","commonSituations":"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.","solutions":["Restart each cluster node via the OS service manager or orchestrator instead of the in-app restart (e.g. systemctl restart sonarqube).","Use the cluster's documented restart/rolling-upgrade procedure for Data Center Edition.","If restart is genuinely needed in-app, run in standalone mode (sonar.cluster.enabled=false).","Automate cluster restarts through the deployment tooling rather than the restart endpoint."],"exampleFix":"// before\ncurl -X POST http://localhost:9000/api/system/restart  // fails on cluster\n// after\nsudo systemctl restart sonarqube  # per node, orchestrated","handlingStrategy":"validation","validationCode":"boolean cluster = Boolean.parseBoolean(props.getOrDefault(\"sonar.cluster.enabled\", \"false\"));\nif (cluster) {\n    throw new UnsupportedOperationException(\"Use OS service restart per node, not /api/system/restart\");\n}","typeGuard":null,"tryCatchPattern":"try { reloader.reload(settings); } catch (IllegalStateException e) { log.warning(\"In-place restart unavailable: \" + e.getMessage()); }","preventionTips":["Check sonar.cluster.enabled before calling the restart endpoint.","Automate cluster restarts via systemd/orchestrator instead of the API.","Document that Data Center Edition requires node-level restarts."],"tags":["cluster","restart","unsupported-operation"],"backgroundTag":"operation-not-supported","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}