SonarSource/sonarqube · error · ForbiddenException

Insufficient privileges

Error message

Insufficient privileges

What it means

api/scannercache/clear wipes the scanner cache used by CI sessions. checkPermission requires the global ADMINISTER (Administer System) permission and throws insufficientPrivilegesException for everyone else. This is a highly privileged maintenance operation, deliberately restricted to system administrators.

Source

Thrown at server/sonar-webserver-webapi/src/main/java/org/sonar/server/scannercache/ws/ClearAction.java:101

      }
    } else {
      cache.clear();
    }
    response.noContent();
  }

  private static void validateParams(ClearRequestDto params) {
    if (params.branchKey != null) {
      checkArgument(
        params.projectKey != null,
        "{} needs to be specified when {} is present",
        PARAM_PROJECT_KEY, PARAM_BRANCH_KEY);
    }
  }

  private void checkPermission() {
    if (!userSession.hasPermission(GlobalPermission.ADMINISTER)) {
      throw insufficientPrivilegesException();
    }
  }
}

View on GitHub (pinned to 184c821202)

Solutions

1. Run the clear operation with a token of a user holding global 'Administer System' permission.
2. Grant 'Administer System' to the automation user via Administration > Security > Global Permissions (or api/permissions/add_user?permission=admin).
3. If only cache invalidation for one project is needed, check whether a less privileged endpoint (api/scannercache/get with SCAN) suffices and rely on cache expiry instead.
4. Confirm the token was not regenerated under a user who lost the admin role.

Example fix

// before: non-admin clears scanner cache
curl -u citoken: -X POST "$SONAR/api/scannercache/clear"

// after: use a system-admin token
curl -u admintoken: -X POST "$SONAR/api/scannercache/clear"

curl -u "$TOKEN": "$SONAR/api/permissions/user?login=$USER" | grep '"permissions":\["admin"

try {
  wsClient.scannerCache().clear();
} catch (ServiceErrorException e) {
  if (e.errors().contains("Insufficient privileges")) {
    throw new IllegalStateException("scannercache/clear requires global Administer System permission");
  }
}

When it happens

Trigger: Calling POST api/scannercache/clear with a token whose user lacks the global 'Administer System' permission — e.g., a project admin or CI scan token attempting cache cleanup.

Common situations: Ops scripts clearing the scanner cache after a SonarQube upgrade run with a non-admin token; users misreading documentation that only the cache GET requires lighter permissions; expired/rotated tokens that lost the admin role.

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
• Insufficient privileges
• Insufficient privileges
• Insufficient privileges
• Insufficient privileges

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