SonarSource/sonarqube · error · IllegalArgumentException

Missing permissions; permission granted on %s

Error message

Missing permissions; permission granted on %s

What it means

checkAppPermissions() compares the permissions required by the SonarQube GitHub integration against the permissions actually granted to the GitHub App by GitHub. If any required permission is missing or has the wrong access level, it throws with a per-permission breakdown of granted vs expected values. This is a configuration validation error, not a runtime failure.

Source

Thrown at server/sonar-alm-client/src/main/java/org/sonar/alm/client/github/GithubApplicationClientImpl.java:206

    // GitHub Enterprise Cloud with data residency - official format: https://api.company.ghe.com
    return lowerCaseHost.startsWith("api.") && lowerCaseHost.endsWith(".ghe.com");
  }

  @Override
  public void checkAppPermissions(GithubAppConfiguration githubAppConfiguration) {
    checkAppPermissions(githubAppConfiguration, GithubAppPermissions.REQUIRED_PERMISSIONS);
  }

  @Override
  public void checkAppPermissions(GithubAppConfiguration githubAppConfiguration, Map<String, String> permissions) {
    Map<String, String> grantedPermissions = getAppPermissions(githubAppConfiguration);
    List<String> missingPermissions = computeMissingPermissions(permissions, grantedPermissions);
    if (!missingPermissions.isEmpty()) {
      String message = missingPermissions.stream()
        .map(perm -> perm + " is '" + grantedPermissions.get(perm) + "', should be '" + permissions.get(perm) + "'")
        .collect(Collectors.joining(", "));

      throw new IllegalArgumentException("Missing permissions; permission granted on " + message);
    }
  }

  @Override
  public List<String> findMissingAppPermissions(GithubAppConfiguration githubAppConfiguration, Map<String, String> permissions) {
    return computeMissingPermissions(permissions, getAppPermissions(githubAppConfiguration));
  }

  private Map<String, String> getAppPermissions(GithubAppConfiguration githubAppConfiguration) {
    AppToken appToken = appSecurity.createAppToken(githubAppConfiguration.getId(), githubAppConfiguration.getPrivateKey());

    String endPoint = "/app";
    GetResponse response;
    try {
      response = githubApplicationHttpClient.get(githubAppConfiguration.getApiEndpoint(), appToken, endPoint);
    } catch (IOException e) {
      LOG.warn(FAILED_TO_REQUEST_BEGIN_MSG + githubAppConfiguration.getApiEndpoint() + endPoint, e);
      throw new IllegalArgumentException("Failed to validate configuration, check URL and Private Key");

View on GitHub (pinned to 184c821202)

Solutions

1. Open the GitHub App settings > Permissions & events and grant exactly the permissions SonarQube lists as missing, with the required access level
2. After changing permissions, have an organization owner approve the new permissions so GitHub actually grants them
3. Reinstall/re-accept the app on the organization if the permission change is pending
4. Run validateConfig again to confirm the granted permissions match

List<String> missing = githubApplicationClient.findMissingAppPermissions(config, requiredPermissions);
if (!missing.isEmpty()) {
  throw new IllegalStateException("GitHub App is missing permissions: " + missing
    + " — grant them in GitHub App settings and have an org admin approve");
}

try {
  githubApplicationClient.validateConfig(config);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Missing permissions")) {
    // surface e.getMessage() to the admin: it lists granted vs required per permission
  }
}

When it happens

Trigger: Calling validateConfig or findMissingAppPermissions when the GitHub App's granted permissions (fetched from GET /app) lack any of the required permissions (e.g. repository_metadata, checks, contents) or grant a lower access level (read instead of read&write).

Common situations: GitHub App registered without all permissions SonarQube requires; permissions changed in GitHub App settings but not re-approved by an org admin; access level downgraded from WRITE to READ; app installed on the org before permissions were updated.

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

• Cannot mint a GitHub installation token for project '%s': in
• Error returned by Bitbucket Cloud: The OAuth client in the B
• Missing URL
• Invalid URL, %s
• Only http and https schemes are supported

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