{"record":{"id":"2c34143e369155a9","repo":"SonarSource/sonarqube","slug":"unable-to-contact-bitbucket-server","errorCode":null,"errorMessage":"Unable to contact Bitbucket server","messagePattern":"Unable to contact Bitbucket server","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"server/sonar-alm-client/src/main/java/org/sonar/alm/client/bitbucketserver/BitbucketServerRestClient.java","lineNumber":158,"sourceCode":"    }\n\n    return builder.build();\n  }\n\n  protected <G> G doCall(Request request, Function<String, G> handler) {\n    String bodyString = getBodyString(request);\n    return applyHandler(handler, bodyString);\n  }\n\n  private String getBodyString(Request request) {\n    try (Response response = client.newCall(request).execute()) {\n      String bodyString = response.body().string();\n      validateResponseBody(response.isSuccessful(), bodyString);\n      handleHttpErrorIfAny(response.isSuccessful(), response.code(), bodyString);\n      return bodyString;\n    } catch (IOException e) {\n      LOG.info(UNABLE_TO_CONTACT_BITBUCKET_SERVER + \": {}\", e.getMessage(), e);\n      throw new IllegalArgumentException(UNABLE_TO_CONTACT_BITBUCKET_SERVER, e);\n    }\n  }\n\n  protected static <G> G applyHandler(Function<String, G> handler, String bodyString) {\n    try {\n      return handler.apply(bodyString);\n    } catch (JsonSyntaxException e) {\n      LOG.info(UNABLE_TO_CONTACT_BITBUCKET_SERVER + \". Unexpected body response was : [{}]\", bodyString);\n      LOG.info(UNABLE_TO_CONTACT_BITBUCKET_SERVER + \": {}\", e.getMessage(), e);\n      throw new IllegalArgumentException(UNABLE_TO_CONTACT_BITBUCKET_SERVER + \", got an unexpected response\", e);\n    }\n  }\n\n  protected static void validateResponseBody(boolean isSuccessful, String bodyString) {\n    if (isSuccessful) {\n      try {\n        buildGson().fromJson(bodyString, Object.class);\n      } catch (JsonParseException e) {","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-alm-client/src/main/java/org/sonar/alm/client/bitbucketserver/BitbucketServerRestClient.java#L140-L176","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the Bitbucket server is reachable from the SonarQube host: curl -v <serverUrl>/rest/api/1.0/projects.","Check DNS, proxy settings (http.proxyHost/https.proxyHost) and firewall rules between SonarQube and Bitbucket.","If TLS is the issue, import the Bitbucket certificate into the JVM truststore (keytool -importcert) or fix the certificate.","Check the accompanying log line for the underlying IOException message."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Optional pre-flight check from the SonarQube host\nnew URL(serverUrl).openConnection().connect(); // throws IOException if unreachable — do this before relying on the integration","typeGuard":null,"tryCatchPattern":"try {\n  // call BitbucketServerRestClient method\n} catch (IllegalArgumentException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Unable to contact Bitbucket server\") && !e.getMessage().contains(\"unexpected response\")) {\n    // treat as network/connectivity failure: alert ops, retry with backoff or degrade feature\n  }\n}","preventionTips":["Monitor Bitbucket Server uptime and network reachability from the SonarQube host.","Configure sane connection timeouts and a proxy if the network requires one.","Import the Bitbucket TLS certificate into the JVM truststore for self-signed setups.","Pin stable DNS names for Bitbucket to avoid migration outages."],"tags":["java","bitbucket-server","network","ioexception"],"backgroundTag":"connection-refused","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}