{"record":{"id":"0f28ad8f9ce0aa46","repo":"SonarSource/sonarqube","slug":"your-global-bitbucket-server-configuration-is-inco","errorCode":null,"errorMessage":"Your global Bitbucket Server configuration is incomplete.","messagePattern":"Your global Bitbucket Server configuration is incomplete\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"server/sonar-alm-client/src/main/java/org/sonar/alm/client/bitbucketserver/BitbucketServerSettingsValidator.java","lineNumber":41,"sourceCode":"import org.sonar.api.config.internal.Settings;\nimport org.sonar.api.server.ServerSide;\nimport org.sonar.db.alm.setting.AlmSettingDto;\n\n@ServerSide\npublic class BitbucketServerSettingsValidator {\n  private final BitbucketServerRestClient bitbucketServerRestClient;\n  private final Encryption encryption;\n\n  public BitbucketServerSettingsValidator(BitbucketServerRestClient bitbucketServerRestClient, Settings settings) {\n    this.bitbucketServerRestClient = bitbucketServerRestClient;\n    this.encryption = settings.getEncryption();\n  }\n\n  public void validate(AlmSettingDto almSettingDto) {\n    String bitbucketUrl = almSettingDto.getUrl();\n    String bitbucketToken = almSettingDto.getDecryptedPersonalAccessToken(encryption);\n    if (bitbucketUrl == null || bitbucketToken == null) {\n      throw new IllegalArgumentException(\"Your global Bitbucket Server configuration is incomplete.\");\n    }\n\n    bitbucketServerRestClient.validateUrl(bitbucketUrl);\n    bitbucketServerRestClient.validateToken(bitbucketUrl, bitbucketToken);\n    bitbucketServerRestClient.validateReadPermission(bitbucketUrl, bitbucketToken);\n  }\n}\n","sourceCodeStart":23,"sourceCodeEnd":49,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-alm-client/src/main/java/org/sonar/alm/client/bitbucketserver/BitbucketServerSettingsValidator.java#L23-L49","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Open Administration > ALM Integrations > Bitbucket Server and fill in both the URL and a personal access token, then save","Re-create the ALM setting via the web API providing both url and personalAccessToken","Verify in the alm_settings table that the URL and encrypted token columns are populated","Regenerate a Bitbucket personal access token with read permission and update the configuration"],"exampleFix":"// before (API call missing token)\nPOST /api/alm_settings/create {\"url\":\"https://bitbucket.example.com\",\"key\":\"bb\"}\n// after\nPOST /api/alm_settings/create {\"url\":\"https://bitbucket.example.com\",\"key\":\"bb\",\"personalAccessToken\":\"<PAT>\"}","handlingStrategy":"validation","validationCode":"// Java: validate the ALM setting before calling the validator/client\nif (almSettingDto == null || almSettingDto.getUrl() == null || almSettingDto.getDecryptedPersonalAccessToken(encryption) == null) {\n  throw new IllegalStateException(\"Bitbucket Server URL and personal access token must both be set before validation\");\n}","typeGuard":"// Java: guard the DTO fields\nstatic boolean hasCompleteBitbucketConfig(AlmSettingDto dto) {\n  return dto != null && dto.getUrl() != null && !dto.getUrl().isBlank();\n}","tryCatchPattern":"try {\n  validator.validate(almSettingDto);\n} catch (IllegalArgumentException e) {\n  // \"Your global Bitbucket Server configuration is incomplete.\"\n  throw new ConfigurationException(\"Set both URL and personal access token in Administration > ALM Integrations > Bitbucket Server\");\n}","preventionTips":["Always provide both URL and personal access token when creating/updating the Bitbucket Server ALM setting via web API or UI","Add a pre-save check on the alm_settings row for null url/token columns","After upgrades or migrations, re-verify global ALM integration fields are intact","Use a PAT with read scope so subsequent validateToken/validateReadPermission calls also succeed"],"tags":["bitbucket","configuration","validation"],"backgroundTag":"missing-required-config-field","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}