SonarSource/sonarqube · error · IllegalStateException

Failed to setup SSL context on ES client

Error message

Failed to setup SSL context on ES client

What it means

getSSLContext loads a PKCS12 key store from disk and builds an SSLContext for the Elasticsearch REST client. Any IOException (missing/unreadable keystore file) or GeneralSecurityException (bad password, invalid keystore format) is wrapped in IllegalStateException 'Failed to setup SSL context on ES client'.

Source

Thrown at server/sonar-main/src/main/java/org/sonar/application/es/EsConnectorImpl.java:182

      if ("true".equalsIgnoreCase(System.getProperty("java.net.preferIPv6Addresses"))) {
        return new HttpHost(scheme, address, host.getHost(), host.getPortOrDefault(9001));
      }
      return new HttpHost(scheme, address, host.getPortOrDefault(9001));
    } catch (UnknownHostException e) {
      throw new IllegalStateException("Can not resolve host [" + host + "]", e);
    }
  }

  private static SSLContext getSSLContext(Path keyStorePath, @Nullable String keyStorePassword) {
    try {
      KeyStore keyStore = KeyStore.getInstance("pkcs12");
      try (InputStream is = Files.newInputStream(keyStorePath)) {
        keyStore.load(is, keyStorePassword == null ? null : keyStorePassword.toCharArray());
      }
      SSLContextBuilder sslBuilder = SSLContexts.custom().loadTrustMaterial(keyStore, null);
      return sslBuilder.build();
    } catch (IOException | GeneralSecurityException e) {
      throw new IllegalStateException("Failed to setup SSL context on ES client", e);
    }
  }

  /**
   * Holds the ES client together with the underlying Rest5Client so we can close the latter on stop().
   */
  private record EsClient(Rest5Client restClient, ElasticsearchClient client) {
  }
}

View on GitHub (pinned to 184c821202)

Solutions

1. Verify the keystore file exists and is readable at the configured path
2. Convert the keystore to PKCS12: keytool -importkeystore -srckeystore ks.jks -deststoretype pkcs12
3. Check/correct the keystore password configured for the ES client
4. Regenerate the keystore if the file is corrupted

Example fix

// before: JKS keystore
keytool -genkeypair -keystore es-keystore.jks
// after: PKCS12 as required
keytool -importkeystore -srckeystore es-keystore.jks -destkeystore es-keystore.p12 -deststoretype pkcs12

Path ks = Paths.get(keyStorePath);
if (!Files.isReadable(ks)) throw new IllegalStateException("ES keystore unreadable: " + ks);
// optionally probe: KeyStore.getInstance("pkcs12").load(Files.newInputStream(ks), password)

static boolean validPkcs12(Path p, String pw) { try (InputStream in = Files.newInputStream(p)) { KeyStore.getInstance("pkcs12").load(in, pw == null ? null : pw.toCharArray()); return true; } catch (Exception e) { return false; } }

try { esConnector.start(); } catch (IllegalStateException e) { if (e.getMessage().contains("Failed to setup SSL context")) { verifyKeystore(); } throw e; }

When it happens

Trigger: Building the ES HTTPS client when the configured keystore path does not exist, is not a valid PKCS12 file, or the provided keyStorePassword is wrong.

Common situations: Using a JKS keystore where PKCS12 is required; a wrong or missing keystore password; the keystore file not being mounted/copied into the deployment; corrupted keystore files.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• Failed to setup SSL context on ES client
• Elasticsearch KeyStore tool exited with code:
• Unable to get default key manager
• if keyStoreType is
• Fail to launch monitor of process [%s]

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