{"record":{"id":"0a7e490e3308f49f","repo":"quarkusio/quarkus","slug":"failed-to-load-keystore","errorCode":null,"errorMessage":"Failed to load keystore","messagePattern":"Failed to load keystore","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"extensions/keycloak-authorization/runtime/src/main/java/io/quarkus/keycloak/pep/runtime/HttpClientBuilder.java","lineNumber":438,"sourceCode":"        String truststorePath = adapterConfig.getTruststore();\n        if (truststorePath != null) {\n            truststorePath = EnvUtil.replace(truststorePath);\n            String truststorePassword = adapterConfig.getTruststorePassword();\n            try {\n                this.truststore = KeystoreUtil.loadKeyStore(truststorePath, truststorePassword);\n            } catch (Exception e) {\n                throw new RuntimeException(\"Failed to load truststore\", e);\n            }\n        }\n        String clientKeystore = adapterConfig.getClientKeystore();\n        if (clientKeystore != null) {\n            clientKeystore = EnvUtil.replace(clientKeystore);\n            String clientKeystorePassword = adapterConfig.getClientKeystorePassword();\n            try {\n                KeyStore clientCertKeystore = KeystoreUtil.loadKeyStore(clientKeystore, clientKeystorePassword);\n                keyStore(clientCertKeystore, clientKeystorePassword);\n            } catch (Exception e) {\n                throw new RuntimeException(\"Failed to load keystore\", e);\n            }\n        }\n\n        HttpClientBuilder.HostnameVerificationPolicy policy = HttpClientBuilder.HostnameVerificationPolicy.WILDCARD;\n        if (adapterConfig.isAllowAnyHostname())\n            policy = HttpClientBuilder.HostnameVerificationPolicy.ANY;\n        connectionPoolSize(adapterConfig.getConnectionPoolSize());\n        hostnameVerification(policy);\n        if (adapterConfig.isDisableTrustManager()) {\n            disableTrustManager();\n        } else {\n            trustStore(truststore);\n        }\n\n        configureProxyForAuthServerIfProvided(adapterConfig);\n\n        if (socketTimeout == -1 && adapterConfig.getSocketTimeout() > 0) {\n            socketTimeout(adapterConfig.getSocketTimeout(), TimeUnit.MILLISECONDS);","sourceCodeStart":420,"sourceCodeEnd":456,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/keycloak-authorization/runtime/src/main/java/io/quarkus/keycloak/pep/runtime/HttpClientBuilder.java#L420-L456","documentation":"Thrown during HttpClientBuilder.build() when the client keystore configured for mutual TLS (client certificate authentication) cannot be loaded via KeystoreUtil.loadKeyStore. This is the client-certificate counterpart of the truststore failure and aborts HTTP client construction.","triggerScenarios":"AdapterConfig defines a client keystore (quarkus.oidc.tls.key-store-file / adapterConfig.getClientKeystore()) but the file path is wrong, the client-keystore password is wrong, the format/type is unsupported, or the file is unreadable in the runtime environment.","commonSituations":"Mounting the keystore in Kubernetes but pointing config at the host path; PKCS12 vs JKS store type mismatch; password containing special characters mangled by env substitution; keystore regenerated with a new password after rotation.","solutions":["Verify the client keystore path resolves correctly at runtime (remember EnvUtil environment substitution) and the file is present/readable.","Confirm client-keystore-password matches the keystore's store password.","Recreate the keystore in a supported format: keytool -genkeypair -keystore client.p12 -storetype PKCS12 and align config (store type).","If mTLS is not required, remove the client-keystore configuration entirely."],"exampleFix":"// before (wrong password / path)\nquarkus.oidc.tls.key-store-file=/etc/certs/client.jks\nquarkus.oidc.tls.key-store-password=oldpass\n// after\nquarkus.oidc.tls.key-store-file=/etc/certs/client.p12\nquarkus.oidc.tls.key-store-password=currentpass\nquarkus.oidc.tls.key-store-file-type=PKCS12","handlingStrategy":"validation","validationCode":"File ksFile = new File(clientKeystorePath);\nif (!ksFile.isFile() || !ksFile.canRead())\n    throw new IllegalStateException(\"Client keystore missing/unreadable: \" + ksFile.getAbsolutePath());\nKeyStore ks = KeyStore.getInstance(\"PKCS12\");\ntry (InputStream in = new FileInputStream(ksFile)) { ks.load(in, clientKeystorePassword.toCharArray()); }","typeGuard":null,"tryCatchPattern":"try {\n    client = HttpClientBuilder.create(adapterConfig).build();\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Failed to load keystore\")) {\n        log.error(\"Check client keystore path/password/type: {}\", adapterConfig.getClientKeystore(), e.getCause());\n    }\n    throw e;\n}","preventionTips":["Confirm the client keystore is packaged/mounted where the app runs.","Validate keystore password after every rotation.","Match the configured keystore type with the actual file format.","Only set client-keystore config when mTLS is actually required."],"tags":["tls","keystore","mtls","configuration","keycloak"],"backgroundTag":"keystore-load-failed","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}