SonarSource/sonarqube · error · IllegalStateException

Error while executing a call to %s. Return code %s. Error me

Error message

Error while executing a call to %s. Return code %s. Error message: %s.

What it means

GenericPaginatedHttpClient.executeCall performs a GET against an external ALM system and requires a 2xx response; any other status raises IllegalStateException embedding the app URL, return code and response body. It signals the remote system responded but rejected the request or is failing. The exception is then re-wrapped by the caller with a generic SonarQube message.

Source

Thrown at server/sonar-alm-client/src/main/java/org/sonar/alm/client/GenericPaginatedHttpClient.java:81

  private void checkRateLimit(@Nullable ApplicationHttpClient.RateLimit rateLimit) {
    if (rateLimit == null) {
      return;
    }
    try {
      GHRateLimit.Record rateLimitRecord = new GHRateLimit.Record(rateLimit.limit(), rateLimit.remaining(), rateLimit.reset());
      rateLimitChecker.checkRateLimit(rateLimitRecord, 0);
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
      LOG.warn(format("Thread interrupted: %s", e.getMessage()), e);
    }
  }

  private GetResponse executeCall(String appUrl, AccessToken token, String endpoint) {
    try {
      GetResponse response = appHttpClient.get(appUrl, token, endpoint);
      if (response.getCode() < 200 || response.getCode() >= 300) {
        throw new IllegalStateException(
          format("Error while executing a call to %s. Return code %s. Error message: %s.", appUrl, response.getCode(), response.getContent().orElse("")));
      }
      return response;
    } catch (Exception e) {
      String errorMessage = format("SonarQube was not able to retrieve resources from external system. Error while executing a paginated call to %s, endpoint:%s.",
        appUrl, endpoint);
      logException(errorMessage, e);
      throw new IllegalStateException(errorMessage + " " + e.getMessage());
    }
  }

  private static void logException(String message, Exception e) {
    if (LOG.isDebugEnabled()) {
      LOG.warn(message, e);
    } else {
      LOG.warn(message, e.getMessage());
    }
  }

View on GitHub (pinned to 184c821202)

Solutions

Check response code and message content reported in the log: fix credentials if 401/403, or fix the URL/project if 404.
Regenerate the personal access token in the ALM system and update it in SonarQube settings.
Verify the project/repository still exists at the configured URL on the external system.
Check the ALM server logs/status if the code is 5xx and retry once the remote system is healthy.

Example fix

// before: token expired, 401 from Azure
// after: PAT updated in SonarQube ALM settings
// Administration > DevOps Platform Integrations > update Personal Access Token

Defensive patterns

Strategy: try-catch

Validate before calling

// precondition check before a paginated import
int code = testConnectionOnce(appUrl, token, firstEndpoint); // returns HTTP status
if (code < 200 || code >= 300) {
  throw new IllegalStateException("Remote system returned HTTP " + code + "; fix token/URL before importing");
}

Try / catch

try {
  paginator.fetchAll(appUrl, token, endpoint);
} catch (IllegalStateException e) {
  LOG.error("ALM paginated call failed: {}", e.getMessage());
  // inspect embedded return code + error message and surface to the user
}

Prevention

Validate the PAT and endpoint with a single cheap API call before starting paginated imports.
Monitor the remote system's status endpoint; retry imports only when it is healthy.
Log response bodies on non-2xx to make diagnosis immediate.
Keep PATs refreshed before their expiry date.

When it happens

Trigger: appHttpClient.get() returns a GetResponse with code outside 200-299: remote returns 404 (wrong endpoint/project), 401/403 (bad PAT), 500 (Azure server error) while SonarQube imports/refreshes devops data.

Common situations: Expired or insufficient-scope personal access token; project deleted or renamed on the ALM side; Azure DevOps server returning 5xx under load; reverse proxy returning 404 for the API path.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

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