SonarSource/sonarqube · error · ForbiddenException

Insufficient privileges

Error message

Insufficient privileges

What it means

ForbiddenException 'Insufficient privileges' from /api/branches/list when the current user has none of: User permission on the project, Scan permission on the project, or global Scan permission. At least one of these is required to see a project's branch list.

Source

Thrown at server/sonar-webserver-webapi/src/main/java/org/sonar/server/branch/ws/ListAction.java:145

    builder.setExcludedFromPurge(branch.isExcludeFromPurge());
    builder.setBranchId(branch.getUuid());
    return builder;
  }

  private static void setBranchStatus(ProjectBranches.Branch.Builder builder, @Nullable MeasureDto qualityGateMeasure) {
    ProjectBranches.Status.Builder statusBuilder = ProjectBranches.Status.newBuilder();
    if (qualityGateMeasure != null) {
      ofNullable(qualityGateMeasure.getString(ALERT_STATUS_KEY)).ifPresent(statusBuilder::setQualityGateStatus);
    }

    builder.setStatus(statusBuilder);
  }

  private void checkPermission(ProjectDto project) {
    if (!userSession.hasEntityPermission(USER, project) &&
        !userSession.hasEntityPermission(ProjectPermission.SCAN, project) &&
        !userSession.hasPermission(SCAN)) {
      throw insufficientPrivilegesException();
    }
  }
}

View on GitHub (pinned to 184c821202)

Solutions

  1. Grant the user 'User' (or at minimum 'Scan') permission on the project via Administration > Projects > Permissions.
  2. Add the user/token owner to a group that has the project permissions.
  3. Use a token belonging to a user with global Scan permission for CI-style reads.
  4. Confirm the project key is correct and the permission applies to that exact project, not a sibling.

Example fix

// before: user has no role on project
GET /api/branches/list?project=my_proj  -> 403
// after: in UI Administration > my_proj > Permissions, grant 'User' to ci-bot
GET /api/branches/list?project=my_proj  -> 200
Defensive patterns

Strategy: validation

Validate before calling

// shell: verify visibility before calling
STATUS=$(curl -s -o /dev/null -w '%{http_code}' -u "$TOKEN:" "$SONAR/api/projects/show?project=$KEY")
[ "$STATUS" = "200" ] || echo "no permission on project $KEY"

Try / catch

try {
  branches = ws.get("/api/branches/list?project=" + key);
} catch (ForbiddenException e) {
  log.warn("User lacks User/Scan permission on {}", key);
  throw e;
}

Prevention

When it happens

Trigger: Calling GET /api/branches/list?project=KEY as a user with no role on that project and no global scan permission; using a token of a user who was removed from the project; querying a private project.

Common situations: CI tokens without project roles; users added to a group that lost the project permission; SonarCloud projects where the token owner isn't a member of the organization/team.

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

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