SonarSource/sonarqube · error · IllegalArgumentException

Restart not allowed for cluster nodes

Error message

Restart not allowed for cluster nodes

What it means

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.

Source

Thrown at server/sonar-webserver-webapi/src/main/java/org/sonar/server/platform/ws/RestartAction.java:65

    this.processCommandWrapper = processCommandWrapper;
    this.restartFlagHolder = restartFlagHolder;
    this.nodeInformation = nodeInformation;
  }

  @Override
  public void define(WebService.NewController controller) {
    controller.createAction("restart")
      .setDescription("Restarts server. Requires 'Administer System' permission. Performs a full restart of the Web, Search and Compute Engine Servers processes."
         + " Does not reload sonar.properties.")
      .setSince("4.3")
      .setPost(true)
      .setHandler(this);
  }

  @Override
  public void handle(Request request, Response response) {
    if (!nodeInformation.isStandalone()) {
      throw new IllegalArgumentException("Restart not allowed for cluster nodes");
    }

    userSession.checkIsSystemAdministrator();

    LOGGER.info("SonarQube restart requested by {}", userSession.getLogin());
    restartFlagHolder.set();
    processCommandWrapper.requestSQRestart();
  }

}

View on GitHub (pinned to 184c821202)

Solutions

1. Do not call api/system/restart on cluster nodes; restart each node via the infrastructure layer (Kubernetes rollout, systemd, service restart).
2. Gate the script on deployment mode: check node info/edition first and skip or use the cluster-appropriate restart path.
3. On DCE, restart the process coordinator / app nodes individually through your orchestrator instead of the Web API.

Example fix

// before
document.System.restart();
// after
if (isStandaloneDeployment()) {
  document.System.restart();
} else {
  restartViaOrchestrator("sonarqube-app-node");
}

const info = await api.system.info();
if (String(info['Edition']).toLowerCase() !== 'community' || isClustered(info)) {
  throw new Error('restart WS unavailable on cluster nodes; restart via orchestrator');
}

function isStandalone(systemInfo) {
  const edition = String(systemInfo['Edition'] ?? '').toLowerCase();
  const stats = systemInfo['Statistics'] ?? '';
  return edition === 'community' && !stats.includes('cluster');
}

try {
  await api.system.restart();
} catch (e) {
  if (e.message.includes('Restart not allowed for cluster nodes')) {
    restartViaOrchestrator();
  } else { throw e; }
}

When it happens

Trigger: 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.

Common situations: 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.

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
• Property [%s] is forbidden
• Invalid value for property %s: [%s], only [%s] are allowed
• Property %s is mandatory
• Unexpected node type

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