{"record":{"id":"67414313fbbc78a2","repo":"SonarSource/sonarqube","slug":"restart-not-allowed-for-cluster-nodes","errorCode":null,"errorMessage":"Restart not allowed for cluster nodes","messagePattern":"Restart not allowed for cluster nodes","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"server/sonar-webserver-webapi/src/main/java/org/sonar/server/platform/ws/RestartAction.java","lineNumber":65,"sourceCode":"    this.processCommandWrapper = processCommandWrapper;\n    this.restartFlagHolder = restartFlagHolder;\n    this.nodeInformation = nodeInformation;\n  }\n\n  @Override\n  public void define(WebService.NewController controller) {\n    controller.createAction(\"restart\")\n      .setDescription(\"Restarts server. Requires 'Administer System' permission. Performs a full restart of the Web, Search and Compute Engine Servers processes.\"\n         + \" Does not reload sonar.properties.\")\n      .setSince(\"4.3\")\n      .setPost(true)\n      .setHandler(this);\n  }\n\n  @Override\n  public void handle(Request request, Response response) {\n    if (!nodeInformation.isStandalone()) {\n      throw new IllegalArgumentException(\"Restart not allowed for cluster nodes\");\n    }\n\n    userSession.checkIsSystemAdministrator();\n\n    LOGGER.info(\"SonarQube restart requested by {}\", userSession.getLogin());\n    restartFlagHolder.set();\n    processCommandWrapper.requestSQRestart();\n  }\n\n}\n","sourceCodeStart":47,"sourceCodeEnd":76,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-webserver-webapi/src/main/java/org/sonar/server/platform/ws/RestartAction.java#L47-L76","documentation":"SonarQube's RestartAction WS restarts the server, but restart is only supported on standalone (non-clustered) installations. On a Data Center Edition / clustered setup, node restarts are managed externally (Kubernetes, process supervisor), so the Web API refuses with this IllegalArgumentException rather than restarting only the local node.","triggerScenarios":"Calling POST api/system/restart while nodeInformation reports a clustered (non-standalone) deployment; e.g. sending the restart request to a Data Center Edition app node.","commonSituations":"Automation scripts that restart SonarQube after plugin installation or upgrade run unchanged against a clustered Data Center Edition instance; ops teams move from single-node to DCE and their restart automation starts failing.","solutions":["Do not call api/system/restart on cluster nodes; restart each node via the infrastructure layer (Kubernetes rollout, systemd, service restart).","Gate the script on deployment mode: check node info/edition first and skip or use the cluster-appropriate restart path.","On DCE, restart the process coordinator / app nodes individually through your orchestrator instead of the Web API."],"exampleFix":"// before\ndocument.System.restart();\n// after\nif (isStandaloneDeployment()) {\n  document.System.restart();\n} else {\n  restartViaOrchestrator(\"sonarqube-app-node\");\n}","handlingStrategy":"validation","validationCode":"const info = await api.system.info();\nif (String(info['Edition']).toLowerCase() !== 'community' || isClustered(info)) {\n  throw new Error('restart WS unavailable on cluster nodes; restart via orchestrator');\n}","typeGuard":"function isStandalone(systemInfo) {\n  const edition = String(systemInfo['Edition'] ?? '').toLowerCase();\n  const stats = systemInfo['Statistics'] ?? '';\n  return edition === 'community' && !stats.includes('cluster');\n}","tryCatchPattern":"try {\n  await api.system.restart();\n} catch (e) {\n  if (e.message.includes('Restart not allowed for cluster nodes')) {\n    restartViaOrchestrator();\n  } else { throw e; }\n}","preventionTips":["Check deployment mode (standalone vs Data Center Edition) before using api/system/restart.","Implement restart logic at the infrastructure layer for clustered installs.","Keep restart automation edition-aware so it works across Community and DCE environments."],"tags":["sonarqube","webapi","cluster","restart"],"backgroundTag":"unsupported-operation","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"}