SonarSource/sonarqube · warning · ForbiddenException

Insufficient privileges

Error message

Insufficient privileges

What it means

ForbiddenException thrown by DefaultLivenessController.livenessCheck when the request carries neither a valid X-Sonar-Passcode header nor an authenticated session with Administer System permission. The endpoint intentionally restricts liveness details to privileged callers.

Source

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

  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. Set sonar.web.systemPasscode in sonar.properties and send it as the X-Sonar-Passcode header
2. Authenticate the caller as a user with Administer System permission
3. Update monitoring/probe configs after changing the passcode
4. If probing unauthenticated is required, ensure a valid passcode is provisioned to the probe

Example fix

// before
curl http://sonarqube:9000/api/v2/system/liveness
// after
curl -H "X-Sonar-Passcode: $SONAR_PASSCODE" http://sonarqube:9000/api/v2/system/liveness

// ensure header is set before calling
if [ -z "$SONAR_PASSCODE" ]; then echo "X-Sonar-Passcode missing" >&2; exit 1; fi
curl -sf -H "X-Sonar-Passcode: $SONAR_PASSCODE" http://sonarqube:9000/api/v2/system/liveness

When it happens

Trigger: Calling GET /api/v2/system/liveness without the X-Sonar-Passcode header matching the configured sonar.web.systemPasscode, and without being logged in as a system admin.

Common situations: Kubernetes probes not configured with the passcode, monitoring scripts missing the header, passcode changed in sonar.properties but not updated in probe configuration.

Understand the failure class

Background: "You do not have permission" / 403 Forbidden errors: authenticated but not allowed — causes and fixes across open-source libraries — this error's family across 31 libraries.

Related errors

• Insufficient privileges
• User does not exist
• User doesn't have rights to requested resource anymore.
• Insufficient privileges
• Parameter requires Administer System permission.

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