apache/shenyu · error · ShenyuException

Could not load key store path

Error message

Could not load key store path ' ${keyStorePath}'

What it means

HttpClientProperties loads the configured key store (keyStorePath) into a KeyStore instance for client-certificate (mTLS) setup. Any failure opening or parsing the store — including wrong password or corrupt file, all caught as Exception — is rethrown as ShenyuException 'Could not load key store path '<path>'' (note the message includes a leading space before the path).

Solutions

1. Verify keyStorePath points to an existing, readable file (prefer an absolute path) and that it is actually mounted in the runtime environment.
2. Confirm keyStorePassword matches the store's password.
3. Match keyStoreType to the file format (PKCS12 for .p12/.pfx, JKS for .jks) — modern default is PKCS12.
4. Validate the store independently with keytool -list -keystore <path> to reproduce the real cause; check the wrapped exception for details.

Example fix

// before
shenyu.httpclient.ssl.key-store-path: /etc/ssl/client.p12
shenyu.httpclient.ssl.key-store-type: JKS
// after
shenyu.httpclient.ssl.key-store-path: /etc/ssl/client.p12
shenyu.httpclient.ssl.key-store-type: PKCS12

File ks = new File(keyStorePath);
if (!ks.isFile() || !ks.canRead()) {
  throw new IllegalStateException("key store not readable: " + ks.getAbsolutePath());
}
// independently verify password + type:
// keytool -list -keystore /etc/ssl/client.p12 -storetype PKCS12 -storepass $PASS

try {
  keyStore = loadKeyStore(keyStorePath, keyStorePassword, keyStoreType);
} catch (ShenyuException e) {
  log.error("key store load failed for {}: check path, password, and store type", keyStorePath, e);
  throw e;
}

When it happens

Trigger: keyStore.load(url.openStream(), keyPassword) fails: the keyStorePath doesn't exist or isn't readable, the keyStorePassword is wrong (Integrity check failed), the file format doesn't match keyStoreType (JKS vs PKCS12), or the store is corrupt.

Common situations: PKCS12 file configured with type JKS, typo'd or stale password after rotation, cert not mounted in the container, relative path resolved against the wrong working directory, key store generated by a newer tool with an incompatible format.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Could not load certificate
• Could not load KeyStore for type and provider
• shenyu.jwt.secretKey is not configured. In a multi-instance…
• shenyu discovery mode current didn't support
• websocket on client open failed, namespaceId is null

AI-assisted analysis of apache/shenyu@567142e072 (2026-09-12). Data as JSON: /api/errors/490a09c6720c8c0f. Report an issue: GitHub.

Appendix: source

Thrown at shenyu-plugin/shenyu-plugin-httpclient/src/main/java/org/apache/shenyu/plugin/httpclient/config/HttpClientProperties.java:1152

         *
         * @return the key store
         */
        public KeyStore createKeyStore() {
            String provider = getKeyStoreProvider();
            String storeType = getKeyStoreType();
            String keyStorePath = getKeyStorePath();
            String keyStorePassword = getKeyStorePassword();
            try {
                KeyStore keyStore = StringUtils.isNotEmpty(provider)
                        ? KeyStore.getInstance(storeType, provider)
                        : KeyStore.getInstance(storeType);
                try {
                    char[] keyPassword = Optional.ofNullable(keyStorePassword)
                            .map(String::toCharArray).orElse(null);
                    URL url = ResourceUtils.getURL(keyStorePath);
                    keyStore.load(url.openStream(), keyPassword);
                } catch (Exception e) {
                    throw new ShenyuException("Could not load key store path ' " + keyStorePath + "'", e);
                }
                return keyStore;
            } catch (KeyStoreException | NoSuchProviderException e) {
                throw new ShenyuException("Could not load KeyStore for type and provider", e);
            }
        }
    }
}

View on GitHub (pinned to 567142e072)