SonarSource/sonarqube · warning · ForbiddenException

Insufficient privileges

Error message

Insufficient privileges

What it means

ForbiddenException thrown by HealthController.getHealth when the request has neither a valid X-Sonar-Passcode header nor a system-admin user session. The health endpoint requires explicit privilege before returning node health details.

Source

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

  private final SystemPasscode systemPasscode;
  private final NodeInformation nodeInformation;
  private final UserSession userSession;

  @Autowired(required=true)
  public HealthController(HealthChecker healthChecker, SystemPasscode systemPasscode, @Nullable NodeInformation nodeInformation,
    @Nullable UserSession userSession) {
    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. Send the configured system passcode in the X-Sonar-Passcode header
2. Use a session of a user holding Administer System permission
3. Align monitoring tooling with the current sonar.web.systemPasscode value

Example fix

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

if [ -z "$SONAR_PASSCODE" ]; then echo "provide X-Sonar-Passcode" >&2; exit 1; fi
curl -sf -H "X-Sonar-Passcode: $SONAR_PASSCODE" http://sonarqube:9000/api/v2/system/health

When it happens

Trigger: GET /api/v2/system/health without X-Sonar-Passcode matching sonar.web.systemPasscode and without an Administer System session.

Common situations: Health-check scripts missing the passcode header, passcode rotated without updating monitoring, non-admin service accounts calling the endpoint.

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
• Liveness check failed
• Insufficient privileges
• Parameter requires Administer System permission.
• %s is not a valid url

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