{"record":{"id":"0e66e580858579d7","repo":"SonarSource/sonarqube","slug":"liveness-check-failed","errorCode":null,"errorMessage":"Liveness check failed","messagePattern":"Liveness check failed","errorType":"exception","errorClass":"IllegalStateException","httpStatus":500,"severity":"error","filePath":"server/sonar-webserver-webapi-v2/src/main/java/org/sonar/server/v2/api/system/controller/DefaultLivenessController.java","lineNumber":46,"sourceCode":"public class DefaultLivenessController implements LivenessController {\n\n  private final LivenessChecker livenessChecker;\n  private final UserSession userSession;\n  private final SystemPasscode systemPasscode;\n\n  public DefaultLivenessController(LivenessChecker livenessChecker, SystemPasscode systemPasscode, @Nullable UserSession userSession) {\n    this.livenessChecker = livenessChecker;\n    this.userSession = userSession;\n    this.systemPasscode = systemPasscode;\n  }\n\n  @Override\n  public void livenessCheck(String requestPassCode) {\n    if (systemPasscode.isValidPasscode(requestPassCode) || isSystemAdmin()) {\n      if (livenessChecker.liveness()) {\n        return;\n      }\n      throw new IllegalStateException(\"Liveness check failed\");\n    }\n    throw new ForbiddenException(\"Insufficient privileges\");\n  }\n\n  private boolean isSystemAdmin() {\n    if (userSession == null) {\n      return false;\n    }\n    return userSession.isSystemAdministrator();\n  }\n\n}\n","sourceCodeStart":28,"sourceCodeEnd":59,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-webserver-webapi-v2/src/main/java/org/sonar/server/v2/api/system/controller/DefaultLivenessController.java#L28-L59","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Inspect server logs for why the liveness checker reports unhealthy","Restart the SonarQube web process/node","If behind Kubernetes, confirm probe configuration isn't racing with a shutdown","Upgrade SonarQube if a known bug causes false liveness failures"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// prefer readiness endpoint that needs no passcode\n// curl -f http://sonarqube:9000/api/v2/system/status","typeGuard":null,"tryCatchPattern":"try {\n    api.livenessCheck(passcode);\n} catch (ServerErrorException e) {\n    if (e.getResponse().getStatus() == 503) markNodeUnhealthy();\n    else if (e.getResponse().getStatus() == 403) fixCredentials();\n}","preventionTips":["Provision sonar.web.systemPasscode to probes via secret management","Update probe/monitoring config whenever the passcode changes","Distinguish 503 (unhealthy) from 403 (auth problem) in monitoring"],"tags":["java","health-check","liveness"],"backgroundTag":"http-error-response","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}