SonarSource/sonarqube · error · IllegalStateException

Failed to fetch GitLab project with ID '%s' from '%s'

Error message

Failed to fetch GitLab project with ID '%s' from '%s'

What it means

This IllegalStateException wraps a GitlabServerException raised by the GitLab application client while fetching a project by numeric ID via GET /projects/:id. It is thrown when GitLab rejects or fails the API call during DevOps platform binding of a project. The original exception is preserved as the cause.

Source

Thrown at server/sonar-webserver-common/src/main/java/org/sonar/server/common/almsettings/gitlab/GitlabDevOpsProjectCreationContextService.java:99

  }

  private String findPersonalAccessTokenOrThrow(AlmSettingDto almSettingDto) {
    try (DbSession dbSession = dbClient.openSession(false)) {
      String userUuid = requireNonNull(userSession.getUuid(), "User UUID cannot be null.");
      Optional<AlmPatDto> almPatDto = dbClient.almPatDao().selectByUserAndAlmSetting(dbSession, userUuid, almSettingDto);
      return almPatDto.map(AlmPatDto::getPersonalAccessToken)
        .orElseThrow(() -> new IllegalArgumentException(format("Personal access token for '%s' is missing", almSettingDto.getKey())));
    }
  }

  private Project fetchGitlabProject(String gitlabUrl, String pat, Long gitlabProjectId) {
    try {
      return gitlabApplicationClient.getProject(
        gitlabUrl,
        pat,
        gitlabProjectId);
    } catch (GitlabServerException e) {
      throw new IllegalStateException(format("Failed to fetch GitLab project with ID '%s' from '%s'", gitlabProjectId, gitlabUrl), e);
    }
  }

  private Optional<String> getDefaultBranchOnGitlab(String gitlabUrl, String pat, long gitlabProjectId) {
    Optional<GitLabBranch> almMainBranch = gitlabApplicationClient.getBranches(gitlabUrl, pat, gitlabProjectId).stream().filter(GitLabBranch::isDefault).findFirst();
    return almMainBranch.map(GitLabBranch::getName);
  }

}

View on GitHub (pinned to 184c821202)

Solutions

1. Verify the GitLab project ID exists: GET <gitlabUrl>/api/v4/projects/<id> with the same PAT
2. Regenerate the PAT with api (read_api) scope and non-expired expiry, and update the ALM setting in SonarQube
3. Confirm the GitLab URL in the DevOps platform configuration is correct and reachable from SonarQube
4. Inspect the cause (GitlabServerException) message/status code to distinguish 401/404 vs connectivity failure

Example fix

// before
long gitlabProjectId = 12345L; // guessed ID
// after
long gitlabProjectId = 42L; // from GitLab UI: Settings > General > Project ID, verified via GET /projects/42

// pre-check
HttpResponse r = client.send(GET gitlabUrl + "/api/v4/projects/" + id, "PRIVATE-TOKEN", pat);
if (r.status == 404) throw new IllegalArgumentException("project id " + id + " not found on " + gitlabUrl);
if (r.status == 401) throw new IllegalArgumentException("PAT invalid or missing api scope");

boolean isReachableGitlabProject(long id, String url, String pat) {
  int s = probeStatus(url + "/api/v4/projects/" + id, pat);
  return s == 200;
}

try {
  project = gitlabApplicationClient.getProject(url, pat, id);
} catch (GitlabServerException e) {
  log.error("GitLab project fetch failed: status={}, cause={}", e.status(), e.getCause(), e);
  throw new IllegalStateException("Failed to fetch GitLab project " + id, e);
}

When it happens

Trigger: Calling createGitlabProject / DevOps project creation with a gitlabProjectId that does not exist in the GitLab instance, an expired/insufficient Personal Access Token, an incorrect gitlabUrl, or a network error reaching GitLab while gitlabApplicationClient.getProject executes.

Common situations: Admin entered a wrong project ID when binding a SonarQube project to GitLab; PAT lacks 'api' scope or was revoked; GitLab URL points to a different instance than the project ID belongs to; GitLab is temporarily down or behind a misconfigured reverse proxy returning 5xx.

Related errors

• GitLab Merge Request did not happen, please check your confi
• Cannot mint a GitLab access token for project '%s': invalid
• Could not validate GitLab write permission. Got an unexpecte
• Forbidden access to GitLab. Verify your token's permissions
• Request was redirected, please provide the correct URL

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