SonarSource/sonarqube · error · IllegalArgumentException

Could not parse GitLab answer to retrieve project branches.

Error message

Could not parse GitLab answer to retrieve project branches. Got a non-json payload as result.

What it means

getBranches calls the GitLab branches API and deserializes the body into a GitLabBranch[] with Gson. A 2xx response whose body is not valid JSON triggers JsonSyntaxException, rethrown as this IllegalArgumentException. The response came back 'successful' but its payload was not the expected JSON branch array.

Source

Thrown at server/sonar-alm-client/src/main/java/org/sonar/alm/client/gitlab/GitlabApplicationClient.java:373

    }
  }

  public List<GitLabBranch> getBranches(String gitlabUrl, String pat, Long gitlabProjectId) {
    String url = format("%s/projects/%s/repository/branches", gitlabUrl, gitlabProjectId);
    LOG.debug("get branches : [{}]", url);
    Request request = new Request.Builder()
      .addHeader(PRIVATE_TOKEN, pat)
      .get()
      .url(url)
      .build();

    try (Response response = client.newCall(request).execute()) {
      checkResponseIsSuccessful(response);
      String body = response.body().string();
      LOG.trace("loading branches payload result : [{}]", body);
      return Arrays.asList(new GsonBuilder().create().fromJson(body, GitLabBranch[].class));
    } catch (JsonSyntaxException e) {
      throw new IllegalArgumentException("Could not parse GitLab answer to retrieve project branches. Got a non-json payload as result.");
    } catch (IOException e) {
      logException(url, e);
      throw new IllegalStateException(e.getMessage(), e);
    }
  }

  public ProjectList searchProjects(String gitlabUrl, String personalAccessToken, @Nullable String projectName,
    @Nullable Integer pageNumber, @Nullable Integer pageSize) {
    String url = format("%s/projects?archived=false&simple=true&membership=true%s%s%s",
      gitlabUrl,
      projectName == null ? "" : ("&search=" + urlEncode(projectName)),
      pageNumber == null ? "" : format("&page=%d", pageNumber),
      pageSize == null ? "" : format("&per_page=%d", pageSize)
    );

    LOG.debug("get projects : [{}]", url);
    Request request = new Request.Builder()
      .addHeader(PRIVATE_TOKEN, personalAccessToken)

View on GitHub (pinned to 184c821202)

Solutions

  1. Verify the GitLab URL and that /api/v4 is reachable directly from the SonarQube server.
  2. Log/inspect the actual response body (trace log 'loading branches payload result').
  3. Check proxy/VPN/WAF configurations that may replace JSON with HTML.
  4. Confirm the repository path is URL-encoded correctly so GitLab doesn't redirect to a web page.
Defensive patterns

Strategy: try-catch

Try / catch

try { List<GitLabBranch> branches = client.getBranches(url, token, repo); } catch (IllegalArgumentException e) { LOG.warn("GitLab branches response was not JSON; check URL/proxy", e); }

Prevention

When it happens

Trigger: Calling getBranches(url, token, repoName) when the successful HTTP response body is HTML, empty, or otherwise unparseable instead of a JSON array of branches.

Common situations: Reverse proxy or WAF serving HTML maintenance pages with 200 status; wrong GitLab URL hitting an SSO login page; empty responses from misconfigured gateways; API path issues causing a rendered HTML 404 page to be served with 2xx after redirects.

Understand the failure class

Background: "Invalid JSON response" and "Failed to parse response" errors: when an API answers 200 but the body isn't the JSON your library expected — this error's family across 28 libraries.

Related errors

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