What causes "Insufficient privileges" in SonarSource/sonarqube?

Set sonar.allowPermissionManagementForProjectAdmins=true in sonar.properties (Administration > Configuration) and restart if needed.

SonarSource/sonarqube · error · ForbiddenException

Insufficient privileges

Error message

Insufficient privileges

What it means

Permission management endpoints (api/permissions/*) allow changing a project's permissions only if the caller has Admin permission on the entity AND the server setting sonar.allowPermissionManagementForProjectAdmins (core.allowPermissionManagementForProjectAdmins) is enabled. PermissionPrivilegeChecker.checkProjectAdmin throws 'Insufficient privileges' when the property is disabled (falling back to the default) or the entity is null/unavailable.

Source

Thrown at server/sonar-webserver-webapi/src/main/java/org/sonar/server/permission/PermissionPrivilegeChecker.java:60

  }

  /**
   * Checks that user is administrator of the specified project
   * @throws org.sonar.server.exceptions.ForbiddenException if user is not administrator
   */
  public static void checkProjectAdmin(UserSession userSession, Configuration config, @Nullable EntityDto entity) {
    userSession.checkLoggedIn();

    if (userSession.hasPermission(GlobalPermission.ADMINISTER)) {
      return;
    }

    boolean allowChangingPermissionsByProjectAdmins = config.getBoolean(CORE_ALLOW_PERMISSION_MANAGEMENT_FOR_PROJECT_ADMINS_PROPERTY)
      .orElse(CORE_ALLOW_PERMISSION_MANAGEMENT_FOR_PROJECT_ADMINS_DEFAULT_VALUE);
    if (entity != null && allowChangingPermissionsByProjectAdmins) {
      userSession.checkEntityPermission(ProjectPermission.ADMIN, entity);
    } else {
      throw insufficientPrivilegesException();
    }
  }
}

View on GitHub (pinned to 184c821202)

Solutions

Set sonar.allowPermissionManagementForProjectAdmins=true in sonar.properties (Administration > Configuration) and restart if needed.
Use a token from a global administrator (global Administer permission) for permission management calls.
Ensure the request targets an existing project so `entity` resolves rather than being null.

Example fix

// before (sonar.properties)
# sonar.allowPermissionManagementForProjectAdmins not set
// after
sonar.allowPermissionManagementForProjectAdmins=true

Defensive patterns

Strategy: validation

Validate before calling

const settings = await get('/api/settings/values?keys=sonar.allowPermissionManagementForProjectAdmins');
const flagEnabled = settings.settings[0] && settings.settings[0].value === 'true';
const authz = await get(`/api/permissions/authorization?projectKey=${key}`);
if (!(authz.permissions.includes('admin') && flagEnabled)) throw new Error('Project-admin permission editing disabled or no project Admin permission');

Type guard

function canEditProjectPermissions(authz, flagEnabled) {
  return Boolean(authz && authz.permissions.includes('admin')) && flagEnabled === true;
}

Try / catch

try {
  await assignProjectPermission(key, user, perm);
} catch (e) {
  if (e.response && e.response.status === 403) {
    throw new Error('Enable sonar.allowPermissionManagementForProjectAdmins or use a global admin token', { cause: e });
  }
  throw e;
}

Prevention

Set sonar.allowPermissionManagementForProjectAdmins=true if project admins must manage permissions.
Use global-admin tokens for permission automation to avoid dependence on the flag.
After upgrades, re-verify this flag since its default is disabled.

When it happens

Trigger: A project admin calls permission WS endpoints while CORE_ALLOW_PERMISSION_MANAGEMENT_FOR_PROJECT_ADMINS_PROPERTY is false (default); or checkProjectAdmin is invoked without a resolvable entity.

Common situations: Upgraded servers where project admins previously could edit permissions now cannot because the flag defaults to disabled; Terraform/API automation assigning project permissions with an admin-scoped-to-project account; instance admins who forgot to enable the setting.

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