SonarSource/sonarqube · error · ServerException

Unsupported in cluster mode

Error message

Unsupported in cluster mode

What it means

ServerException with HTTP 501 thrown by HealthController's private getHealth() when the node is part of a cluster (nodeInformation is present and not standalone). The v2 system health endpoint only supports standalone SonarQube instances; cluster health must be obtained elsewhere.

Source

Thrown at server/sonar-webserver-webapi-v2/src/main/java/org/sonar/server/v2/api/system/controller/HealthController.java:75

    this.healthChecker = healthChecker;
    this.systemPasscode = systemPasscode;
    this.nodeInformation = nodeInformation;
    this.userSession = userSession;
  }

  @GetMapping
  public Health getHealth(@RequestHeader(value = "X-Sonar-Passcode", required = false) String requestPassCode) {
    if (systemPasscode.isValidPasscode(requestPassCode) || isSystemAdmin()) {
      return getHealth();
    }
    throw new ForbiddenException("Insufficient privileges");
  }

  private Health getHealth() {
    if (nodeInformation == null || nodeInformation.isStandalone()) {
      return healthChecker.checkNode();
    }
    throw new ServerException(HTTP_NOT_IMPLEMENTED, "Unsupported in cluster mode");
  }

  private boolean isSystemAdmin() {
    if (userSession == null) {
      return false;
    }
    return userSession.isSystemAdministrator();
  }
}

View on GitHub (pinned to 184c821202)

Solutions

1. Use the cluster-appropriate health endpoint (e.g. api/system/health on the app node or the cluster health API) instead
2. Run the call against a standalone node if that's the intent
3. Check nodeInformation configuration to confirm deployment mode

// call cluster health instead when on DCE
// app nodes: GET api/system/health ; compute cluster health from node statuses

try {
    health = api.v2SystemHealth(passcode);
} catch (ServerErrorException e) {
    if (e.getResponse().getStatus() == 501) {
        health = clusterHealthApi.get(); // fallback for DCE
    }
}

When it happens

Trigger: Calling GET /api/v2/system/health with valid authorization on an Application/Cluster (Data Center Edition) node.

Common situations: Same monitoring scripts used against both standalone and DCE installations; DCE customers expecting the standalone health API to work on cluster nodes.

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

• state reset is not supported in 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]
• %s is not a valid url
• Error while executing a call to %s. Return code %s. Error me

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