SonarSource/sonarqube · error · IllegalArgumentException

Unable to contact Bitbucket server

Error message

Unable to contact Bitbucket server

What it means

getBodyString wraps the HTTP response-body read in a try/catch for IOException. Any network-level failure while contacting the Bitbucket server (connection refused, DNS failure, TLS handshake error, timeouts, socket reset) is logged and rethrown as IllegalArgumentException('Unable to contact Bitbucket server'). It signals the request never got a usable HTTP response.

Source

Thrown at server/sonar-alm-client/src/main/java/org/sonar/alm/client/bitbucketserver/BitbucketServerRestClient.java:158

    }

    return builder.build();
  }

  protected <G> G doCall(Request request, Function<String, G> handler) {
    String bodyString = getBodyString(request);
    return applyHandler(handler, bodyString);
  }

  private String getBodyString(Request request) {
    try (Response response = client.newCall(request).execute()) {
      String bodyString = response.body().string();
      validateResponseBody(response.isSuccessful(), bodyString);
      handleHttpErrorIfAny(response.isSuccessful(), response.code(), bodyString);
      return bodyString;
    } catch (IOException e) {
      LOG.info(UNABLE_TO_CONTACT_BITBUCKET_SERVER + ": {}", e.getMessage(), e);
      throw new IllegalArgumentException(UNABLE_TO_CONTACT_BITBUCKET_SERVER, e);
    }
  }

  protected static <G> G applyHandler(Function<String, G> handler, String bodyString) {
    try {
      return handler.apply(bodyString);
    } catch (JsonSyntaxException e) {
      LOG.info(UNABLE_TO_CONTACT_BITBUCKET_SERVER + ". Unexpected body response was : [{}]", bodyString);
      LOG.info(UNABLE_TO_CONTACT_BITBUCKET_SERVER + ": {}", e.getMessage(), e);
      throw new IllegalArgumentException(UNABLE_TO_CONTACT_BITBUCKET_SERVER + ", got an unexpected response", e);
    }
  }

  protected static void validateResponseBody(boolean isSuccessful, String bodyString) {
    if (isSuccessful) {
      try {
        buildGson().fromJson(bodyString, Object.class);
      } catch (JsonParseException e) {

View on GitHub (pinned to 184c821202)

Solutions

1. Verify the Bitbucket server is reachable from the SonarQube host: curl -v <serverUrl>/rest/api/1.0/projects.
2. Check DNS, proxy settings (http.proxyHost/https.proxyHost) and firewall rules between SonarQube and Bitbucket.
3. If TLS is the issue, import the Bitbucket certificate into the JVM truststore (keytool -importcert) or fix the certificate.
4. Check the accompanying log line for the underlying IOException message.

// Optional pre-flight check from the SonarQube host
new URL(serverUrl).openConnection().connect(); // throws IOException if unreachable — do this before relying on the integration

try {
  // call BitbucketServerRestClient method
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unable to contact Bitbucket server") && !e.getMessage().contains("unexpected response")) {
    // treat as network/connectivity failure: alert ops, retry with backoff or degrade feature
  }
}

When it happens

Trigger: Any doGet/doCall request to Bitbucket (e.g. fetching branches for project/repo) where response.body().string() or the underlying call throws IOException: server down, wrong port, hostname unresolvable, proxy misconfigured, TLS certificate rejected, connection timeout.

Common situations: Bitbucket Server stopped or migrated to a new host; firewalls blocking SonarQube -> Bitbucket traffic; self-signed certificates not imported into the JVM truststore; wrong port in the server URL; Docker/network isolation between containers.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• SonarQube was not able to retrieve resources from external s
• %s for request [%s]: [%s]
• url must start with http:// or https://
• Unable to contact Bitbucket server, got an unexpected respon
• Unexpected response from Bitbucket server

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