SonarSource/sonarqube · error · IllegalArgumentException

Error returned by Bitbucket Cloud: The OAuth client in the B

Error message

Error returned by Bitbucket Cloud: The OAuth client in the Bitbucket workspace is not configured with the permission to read pull requests.

What it means

During Bitbucket Cloud workspace validation, after exchanging the OAuth client credentials for a token, BitbucketCloudRestClient checks the token's scope. If the scope is null or does not contain 'pullrequest', it throws IllegalArgumentException with 'Error returned by Bitbucket Cloud: ' plus MISSING_PULL_REQUEST_READ_PERMISSION, because SonarQube's Bitbucket Cloud integration requires OAuth client pull-request read permission.

Source

Thrown at server/sonar-alm-client/src/main/java/org/sonar/alm/client/bitbucket/bitbucketcloud/BitbucketCloudRestClient.java:105

  protected BitbucketCloudRestClient(OkHttpClient bitBucketCloudHttpClient, String bitbucketCloudEndpoint, String accessTokenEndpoint) {
    this.client = bitBucketCloudHttpClient;
    this.bitbucketCloudEndpoint = bitbucketCloudEndpoint;
    this.accessTokenEndpoint = accessTokenEndpoint;
  }

  /**
   * Validate parameters provided.
   */
  public void validate(String clientId, String clientSecret, String workspace) {
    Token token = validateAccessToken(clientId, clientSecret);

    if (token.getScope() == null || !token.getScope().contains("pullrequest")) {
      LOG.atInfo()
        .addArgument(MISSING_PULL_REQUEST_READ_PERMISSION)
        .addArgument(() -> String.format(SCOPE, token.getScope()))
        .log("{}{}");
      throw new IllegalArgumentException(ERROR_BBC_SERVERS + ": " + MISSING_PULL_REQUEST_READ_PERMISSION);
    }

    try {
      doGet(token.getAccessToken(), buildUrl("/repositories/" + workspace), r -> null);
    } catch (NotFoundException | IllegalStateException | BitbucketCloudException e) {
      throw new IllegalArgumentException(e.getMessage());
    }
  }

  /**
   * Validate parameters provided.
   */
  public void validateApiToken(String encodedApiTokenCredentials, String workspace) {
    try {
      doGetWithApiToken(encodedApiTokenCredentials, buildUrl("/repositories/" + workspace), r -> null);
    } catch (NotFoundException | IllegalStateException e) {
      throw new IllegalArgumentException(e.getMessage());
    }

View on GitHub (pinned to 184c821202)

Solutions

In Bitbucket Cloud, open Workspace Settings > OAuth consumers, edit the consumer used by SonarQube.
Add the 'Pull requests: Read' permission (plus Account/Email as required) and save.
Re-run the SonarQube ALM setting validation with the same clientId/clientSecret.

Example fix

// before (OAuth consumer permissions): Account: Read, Email: Read
// after: Account: Read, Email: Read, Pull requests: Read

Defensive patterns

Strategy: validation

Validate before calling

// Before saving SonarQube settings, verify the OAuth consumer in Bitbucket Cloud:
// Workspace Settings > OAuth consumers > <consumer> must include 'Pull requests: Read'.
// Optionally probe: exchange credentials and assert token scope contains "pullrequest".

Try / catch

try {
  bbClient.validate(clientId, clientSecret, workspace);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("read pull requests")) {
    // guide admin: grant Pull requests: Read to the OAuth consumer
  }
}

Prevention

Create the Bitbucket Cloud OAuth consumer with Account: Read, Email: Read, Pull requests: Read from the start.
Re-check consumer permissions after any workspace settings edit.
Keep a runbook of required scopes for SonarQube's Bitbucket Cloud integration.

When it happens

Trigger: Calling validate(clientId, clientSecret, workspace) where the OAuth consumer in the Bitbucket workspace was created without the 'Pull requests: Read' permission, so the exchanged token's scope lacks 'pullrequest'.

Common situations: Admin creating the OAuth consumer in Bitbucket Cloud settings and only granting account/email scopes; editing an existing consumer and unchecking Pull requests; workspace OAuth app configured before SonarQube documented its required scopes.

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