SonarSource/sonarqube · error · ForbiddenException

Insufficient privileges

Error message

Insufficient privileges

What it means

The api/qualitygates/get_by_project web service refuses to return the quality gate effective for a project because the authenticated user holds neither the USER nor the ADMIN project permission on that project. The handler explicitly checks both entity permissions after resolving the project key and throws insufficientPrivilegesException() when neither is granted. Quality gate data is considered project-scoped information, so read access requires at least USER-level project membership.

Source

Thrown at server/sonar-webserver-webapi/src/main/java/org/sonar/server/qualitygate/ws/GetByProjectAction.java:91

        new Change("8.4", "Field 'id' in the response is deprecated. Format changes from integer to string."),
        new Change("6.6", "The parameter 'projectId' has been removed"),
        new Change("6.6", "The parameter 'projectKey' has been renamed to 'project'"),
        new Change("6.6", "This webservice is now part of the public API"));

    action.createParam(PARAM_PROJECT)
      .setDescription("Project key")
      .setExampleValue(KEY_PROJECT_EXAMPLE_001)
      .setRequired(true);
  }

  @Override
  public void handle(Request request, Response response) throws Exception {
    try (DbSession dbSession = dbClient.openSession(false)) {
      ProjectDto project = componentFinder.getProjectByKey(dbSession, request.mandatoryParam(PARAM_PROJECT));

      if (!userSession.hasEntityPermission(USER, project) &&
          !userSession.hasEntityPermission(ADMIN, project)) {
        throw insufficientPrivilegesException();
      }

      QualityGateData data = qualityGateFinder.getEffectiveQualityGate(dbSession, project);

      writeProtobuf(buildResponse(data), request, response);
    }
  }

  private static GetByProjectResponse buildResponse(QualityGateData qg) {
    GetByProjectResponse.Builder response = GetByProjectResponse.newBuilder();

    response.getQualityGateBuilder()
      .setName(qg.getName())
      .setDefault(qg.isDefault());

    return response.build();
  }

View on GitHub (pinned to 184c821202)

Solutions

1. In SonarQube UI or via api/permissions/add_user, grant the calling user USER (or ADMIN) project permission on the project being queried.
2. Use a token belonging to a user who is already a member of the project.
3. If the intent is CI-only access, grant the project SCAN permission and use api/qualitygates/project_status instead (see ProjectStatusAction).
4. Verify the project key is correct — a mistyped key may resolve to a project the user has no rights on.

Example fix

// before: user queries with a personal token lacking project membership
curl -u mytoken: $SONAR/api/qualitygates/get_by_project?project=my.project

// after: grant USER permission first
curl -u admintoken: -X POST "$SONAR/api/permissions/add_user?projectKey=my.project&permission=user&login=jdoe"

// Java-side pre-check is not exposed to clients; on the client, verify membership first:
curl -u "$TOKEN": "$SONAR/api/permissions/users?projectKey=my.project&login=$USER" | grep '"permission":"user"'

try {
  ProjectQualityGate gate = wsClient.qualityGates().getByProject(req);
} catch (ServiceErrorException e) {
  if (e.errors().stream().anyMatch(m -> m.contains("Insufficient privileges"))) {
    // request USER/ADMIN project permission or fall back to project_status
  }
}

When it happens

Trigger: Calling GET api/qualitygates/get_by_project with a project key on which the current token's user has no USER or ADMIN project permission. E.g., a CI or script token whose user was never added to the project, or a user querying another team's project key.

Common situations: Scripts using an old token whose project memberships were revoked; users without SonarQube access requesting gate status for a project they can see in CI but not in SonarQube; project key typos causing the lookup to hit a different project the user lacks access to.

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/f6b9b76697dcdc84. Report an issue: GitHub.