SonarSource/sonarqube · error · ServerException

parameter %s requires Administer System permission.

Error message

parameter %s requires Administer System permission.

What it means

SonarQube's user SearchAction rejects requests that supply admin-only query parameters (e.g. q, groups in some versions) without the Administer System permission, throwing a ServerException with HTTP 403. The filter checks whether the parameter is present in the request and if so demands elevated rights regardless of the value. It exists to keep user enumeration from non-privileged users.

Source

Thrown at server/sonar-webserver-webapi/src/main/java/org/sonar/server/user/ws/SearchAction.java:214

      .setQuery(request.param(TEXT_QUERY))
      .setDeactivated(request.mandatoryParamAsBoolean(DEACTIVATED_PARAM))
      .setManaged(request.paramAsBoolean(MANAGED_PARAM))
      .setLastConnectionDateFrom(request.param(LAST_CONNECTION_DATE_FROM))
      .setLastConnectionDateTo(request.param(LAST_CONNECTION_DATE_TO))
      .setSonarLintLastConnectionDateFrom(request.param(SONAR_LINT_LAST_CONNECTION_DATE_FROM))
      .setSonarLintLastConnectionDateTo(request.param(SONAR_LINT_LAST_CONNECTION_DATE_TO))
      .setExternalLogin(request.param(EXTERNAL_IDENTITY))
      .setPage(request.mandatoryParamAsInt(PAGE))
      .setPageSize(pageSize)
      .build();
  }

  private static void throwIfParameterValuePresent(Request request, String parameter) {
    Optional.ofNullable(request.param(parameter)).ifPresent(v -> throwForbiddenFor(parameter));
  }

  private static void throwForbiddenFor(String parameterName) {
    throw new ServerException(403, "parameter " + parameterName + " requires Administer System permission.");
  }

}

View on GitHub (pinned to 184c821202)

Solutions

1. Use a token belonging to an account with the Administer System global permission (generate via My Account > Security, or grant the permission in Administration > Security > Global Permissions).
2. Remove the restricted query parameter from the request; unfiltered search results are returned to non-admin callers.
3. Check which account the token maps to: GET api/authentication/validate or api/users/current, then verify its global permissions.
4. If users legitimately need filtered lookups, consider delegating to an admin service or an API wrapper that holds admin rights.

Example fix

// before: project-scoped token calling filtered search
curl -u "$PROJECT_TOKEN:" 'https://sonar/api/users/search?q=jdoe'
// after: admin token, or drop the restricted param
curl -u "$ADMIN_TOKEN:" 'https://sonar/api/users/search?q=jdoe'
# or for non-admin callers:
curl -u "$TOKEN:" 'https://sonar/api/users/search'

const me = await fetch(`${base}/api/users/current`, {headers: auth}).then(r => r.json());
const isAdmin = me.permissions?.global?.includes('admin');
if (params.q && !isAdmin) throw new Error('q parameter requires Administer System permission; drop it or use an admin token');

function canFilterUsers(me) {
  return Array.isArray(me?.permissions?.global) && me.permissions.global.includes('admin');
}

try {
  return await searchUsers(params);
} catch (e) {
  if (e.status === 403 && /requires Administer System permission/.test(e.message)) {
    return searchUsers({}); // retry unfiltered
  }
  throw e;
}

When it happens

Trigger: GET api/users/search while including admin-restricted parameters (such as q) while authenticated as a user (or token) lacking the Administer System global permission.

Common situations: CI scripts using a project-analysis token instead of a global-admin token; self-service portal calling user search with filters; after downgrading an account's permissions; token belongs to a team admin not a global admin.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

• Your GitLab token has insufficient scope
• Forbidden access to GitLab. Verify your token's permissions
• Insufficient privileges
• You're not authorized to push analysis results to the SonarQ
• noPermissionSourceMessage(projectKey, reason)

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