SonarSource/sonarqube · error · IllegalStateException

Liveness check failed

Error message

Liveness check failed

What it means

IllegalStateException thrown by DefaultLivenessController.livenessCheck when the request is authorized (valid X-Sonar-Passcode header or system admin session) but the livenessChecker reports the node is not alive. It is surfaced by the liveness Web API v2 endpoint to indicate the SonarQube process considers itself unhealthy.

Source

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

public class DefaultLivenessController implements LivenessController {

  private final LivenessChecker livenessChecker;
  private final UserSession userSession;
  private final SystemPasscode systemPasscode;

  public DefaultLivenessController(LivenessChecker livenessChecker, SystemPasscode systemPasscode, @Nullable UserSession userSession) {
    this.livenessChecker = livenessChecker;
    this.userSession = userSession;
    this.systemPasscode = systemPasscode;
  }

  @Override
  public void livenessCheck(String requestPassCode) {
    if (systemPasscode.isValidPasscode(requestPassCode) || isSystemAdmin()) {
      if (livenessChecker.liveness()) {
        return;
      }
      throw new IllegalStateException("Liveness check failed");
    }
    throw new ForbiddenException("Insufficient privileges");
  }

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

}

View on GitHub (pinned to 184c821202)

Solutions

1. Inspect server logs for why the liveness checker reports unhealthy
2. Restart the SonarQube web process/node
3. If behind Kubernetes, confirm probe configuration isn't racing with a shutdown
4. Upgrade SonarQube if a known bug causes false liveness failures

// prefer readiness endpoint that needs no passcode
// curl -f http://sonarqube:9000/api/v2/system/status

try {
    api.livenessCheck(passcode);
} catch (ServerErrorException e) {
    if (e.getResponse().getStatus() == 503) markNodeUnhealthy();
    else if (e.getResponse().getStatus() == 403) fixCredentials();
}

When it happens

Trigger: GET /api/v2/system/liveness with a correct passcode or admin session while livenessChecker.liveness() returns false (e.g. process is shutting down or web process cannot reach required subsystems).

Common situations: Kubernetes liveness probes hitting a node mid-shutdown or in a wedged state, load balancer health checks during upgrade, monitoring alerting on a hung web process.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• Insufficient privileges
• %s is not a valid url
• Error while executing a call to %s. Return code %s. Error me
• SonarQube was not able to retrieve resources from external s
• generateErrorMessage(body)

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