SonarSource/sonarqube · error · IllegalArgumentException

Your global Bitbucket Server configuration is incomplete.

Error message

Your global Bitbucket Server configuration is incomplete.

What it means

BitbucketServerSettingsValidator.validate checks the global ALM setting before contacting the server. If either the URL or the decrypted personal access token is null, it throws IllegalArgumentException("Your global Bitbucket Server configuration is incomplete.") without any network call. It is a guard ensuring mandatory global configuration fields exist.

Source

Thrown at server/sonar-alm-client/src/main/java/org/sonar/alm/client/bitbucketserver/BitbucketServerSettingsValidator.java:41

import org.sonar.api.config.internal.Settings;
import org.sonar.api.server.ServerSide;
import org.sonar.db.alm.setting.AlmSettingDto;

@ServerSide
public class BitbucketServerSettingsValidator {
  private final BitbucketServerRestClient bitbucketServerRestClient;
  private final Encryption encryption;

  public BitbucketServerSettingsValidator(BitbucketServerRestClient bitbucketServerRestClient, Settings settings) {
    this.bitbucketServerRestClient = bitbucketServerRestClient;
    this.encryption = settings.getEncryption();
  }

  public void validate(AlmSettingDto almSettingDto) {
    String bitbucketUrl = almSettingDto.getUrl();
    String bitbucketToken = almSettingDto.getDecryptedPersonalAccessToken(encryption);
    if (bitbucketUrl == null || bitbucketToken == null) {
      throw new IllegalArgumentException("Your global Bitbucket Server configuration is incomplete.");
    }

    bitbucketServerRestClient.validateUrl(bitbucketUrl);
    bitbucketServerRestClient.validateToken(bitbucketUrl, bitbucketToken);
    bitbucketServerRestClient.validateReadPermission(bitbucketUrl, bitbucketToken);
  }
}

View on GitHub (pinned to 184c821202)

Solutions

  1. Open Administration > ALM Integrations > Bitbucket Server and fill in both the URL and a personal access token, then save
  2. Re-create the ALM setting via the web API providing both url and personalAccessToken
  3. Verify in the alm_settings table that the URL and encrypted token columns are populated
  4. Regenerate a Bitbucket personal access token with read permission and update the configuration

Example fix

// before (API call missing token)
POST /api/alm_settings/create {"url":"https://bitbucket.example.com","key":"bb"}
// after
POST /api/alm_settings/create {"url":"https://bitbucket.example.com","key":"bb","personalAccessToken":"<PAT>"}
Defensive patterns

Strategy: validation

Validate before calling

// Java: validate the ALM setting before calling the validator/client
if (almSettingDto == null || almSettingDto.getUrl() == null || almSettingDto.getDecryptedPersonalAccessToken(encryption) == null) {
  throw new IllegalStateException("Bitbucket Server URL and personal access token must both be set before validation");
}

Type guard

// Java: guard the DTO fields
static boolean hasCompleteBitbucketConfig(AlmSettingDto dto) {
  return dto != null && dto.getUrl() != null && !dto.getUrl().isBlank();
}

Try / catch

try {
  validator.validate(almSettingDto);
} catch (IllegalArgumentException e) {
  // "Your global Bitbucket Server configuration is incomplete."
  throw new ConfigurationException("Set both URL and personal access token in Administration > ALM Integrations > Bitbucket Server");
}

Prevention

When it happens

Trigger: Calling validate with an AlmSettingDto whose url is null or whose decrypted personal access token is null — e.g. during Bitbucket Server ALM configuration update or when computing the provisioning/CA cert job before the setting is fully saved.

Common situations: Bitbucket Server ALM integration created without entering the personal access token; token removed or failed to save; database row with null encrypted token; calling the ws api/update_alm_setting with only some fields; migration/version upgrade left the setting incomplete.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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