SonarSource/sonarqube · error · IllegalArgumentException

Your Gitlab global configuration is incomplete. The GitLab U

Error message

Your Gitlab global configuration is incomplete. The GitLab URL must be set.

What it means

GitlabGlobalSettingsValidator.validate checks the global GitLab ALM configuration. When the GitLab URL is null (not configured in global ALM settings), validation fails immediately with this IllegalArgumentException before any remote call is attempted. The global GitLab integration cannot be used or tested without a URL.

Source

Thrown at server/sonar-alm-client/src/main/java/org/sonar/alm/client/gitlab/GitlabGlobalSettingsValidator.java:66

  private static final String API_SCOPE = "api";

  private final Encryption encryption;
  private final GitlabApplicationClient gitlabApplicationClient;

  public GitlabGlobalSettingsValidator(GitlabApplicationClient gitlabApplicationClient, Settings settings) {
    this.encryption = settings.getEncryption();
    this.gitlabApplicationClient = gitlabApplicationClient;
  }

  public void validate(AlmSettingDto almSettingDto) {
    String gitlabUrl = almSettingDto.getUrl();
    String accessToken = almSettingDto.getDecryptedPersonalAccessToken(encryption);
    validate(ValidationMode.COMPLETE, gitlabUrl, accessToken);
  }

  public void validate(ValidationMode validationMode, @Nullable String gitlabApiUrl, @Nullable String accessToken) {
    if (gitlabApiUrl == null) {
      throw new IllegalArgumentException("Your Gitlab global configuration is incomplete. The GitLab URL must be set.");
    }
    gitlabApplicationClient.checkUrl(gitlabApiUrl);
    if (ValidationMode.AUTH_ONLY.equals(validationMode)) {
      return;
    }

    String decryptedToken = getDecryptedToken(accessToken);
    if (decryptedToken == null) {
      throw new IllegalArgumentException("Your Gitlab global configuration is incomplete. The GitLab access token must be set.");
    }
    gitlabApplicationClient.checkToken(gitlabApiUrl, decryptedToken);
    gitlabApplicationClient.checkReadPermission(gitlabApiUrl, decryptedToken);
    gitlabApplicationClient.checkWritePermission(gitlabApiUrl, decryptedToken);
  }

  /**
   * Whether the given configuration's token has the {@code api} scope, the only scope that grants the write access
   * the Remediation Agent needs (create branches, open merge requests). Introspects the token directly via

View on GitHub (pinned to 184c821202)

Solutions

1. Set the GitLab URL in Administration > Configuration > DevOps Platform Integration (e.g. https://gitlab.example.com).
2. Via API/WebService, ensure the alm_settings update includes the url parameter before validating.
3. Re-create or repair the ALM setting row so almSettingDto.getUrl() returns the instance URL.
4. Check the client passes the URL correctly to the validator (not null from decryption/config layer).

Example fix

// before: validating with missing URL
validator.validate(ValidationMode.COMPLETE, null, accessToken);
// after: guard/ensure URL configured first
if (almSettingDto.getUrl() != null) {
  validator.validate(ValidationMode.COMPLETE, almSettingDto.getUrl(), accessToken);
}

if (almSettingDto == null || almSettingDto.getUrl() == null || almSettingDto.getUrl().isBlank()) {
  throw new IllegalStateException("Set the GitLab URL in DevOps Platform Integration settings before validating");
}

boolean hasGitlabUrl(AlmSettingDto dto) { return dto != null && dto.getUrl() != null && !dto.getUrl().isBlank(); }

try { validator.validate(almSettingDto, encryption); } catch (IllegalArgumentException e) { /* prompt admin to set GitLab URL */ }

When it happens

Trigger: Calling validate(almSettingDto, encryption) or validate(validationMode, null, accessToken) when the GitLab global ALM setting has no URL stored — e.g. testing the configuration before the URL was saved, or after the URL field was cleared.

Common situations: Setting up GitLab integration for the first time and hitting 'Validate' before filling the URL; configuration import/migration losing the url field; API calls creating ALM settings without the url property; clearing the URL in Administration > DevOps Platform Integration.

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

• Your Gitlab global configuration is incomplete. The GitLab a
• The property '%s' property is empty while it is mandatory.
• allowedGroups cannot be empty when Auto-provisioning is enab
• allowAllGroups can only be enabled when Auto-provisioning is
• allowAllGroups cannot be enabled when the GitLab URL is gitl

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