apache/shenyu · error · ShenyuException

Cannot read the sni mod

Error message

Cannot read the sni mod

What it means

At ShenyuNettyWebServerConfiguration.nettyReactiveWebServerFactory this ShenyuException is a configuration guard thrown while customizing the Netty HTTPS server: SNI is enabled but the 'shenyu.sni.mod' property is neither 'manual' nor 'k8s' (the only two supported certificate-provisioning modes), so the factory cannot decide how to load certificates. It fires at gateway startup and aborts creation of the secure web server factory until the property is set to a supported value.

Solutions

1. Change sni.mod to exactly 'manual' or 'k8s'
2. If you intended Kubernetes secret discovery, use mod: k8s together with the k8s starter
3. If SNI is not needed, set sni.enabled=false

Example fix

# before
sni:
  enabled: true
  mod: kubernetes
# after
sni:
  enabled: true
  mod: k8s

String mod = env.getProperty("shenyu.server.netty.sni.mod");
if (env.getProperty("shenyu.server.netty.sni.enabled", Boolean.class, false)
        && !"manual".equals(mod) && !"k8s".equals(mod)) {
    throw new IllegalArgumentException("sni.mod must be 'manual' or 'k8s', got: " + mod);
}

try {
    SpringApplication.run(GatewayApplication.class, args);
} catch (Exception e) {
    if (rootCauseOf(e, ShenyuException.class).map(x -> x.getMessage().contains("Cannot read the sni mod")).orElse(false)) {
        log.error("Fix shenyu.server.netty.sni.mod to manual|k8s");
    } else throw e;
}

When it happens

Trigger: Setting shenyu.server.netty.sni.mod to any value other than 'manual' or 'k8s' (typo, capitalized value, wrong config key spillover).

Common situations: Typos like 'Manual', 'kubernetes', or 'auto'; copying mode names from other gateway products; stale config from a version where other modes existed.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• At least one certificate is required
• Can not find shenyuSniAsyncMapping bean
• The sslCrtAndKeys can not be null
• Could not load KeyStore for type and provider
• Can not read cert and key from default secret

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

Appendix: source

Thrown at shenyu-spring-boot-starter/shenyu-spring-boot-starter-gateway/src/main/java/org/apache/shenyu/springboot/starter/netty/ShenyuNettyWebServerConfiguration.java:130

                            shenyuSniAsyncMapping.addSslCertificate(certificate);
                        } catch (IOException e) {
                            LOG.error("add certificate error", e);
                        }
                    }

                    SslCrtAndKeyFile defaultCert = certificates.get(0);
                    TcpSslContextSpec defaultSpec = TcpSslContextSpec.forServer(new File(defaultCert.getKeyCertChainFile()),
                            new File(defaultCert.getKeyFile()));
                    
                    server = server.secure(spec -> spec.sslContext(defaultSpec)
                                .setSniAsyncMappings(shenyuSniAsyncMapping), false);
                } else if ("k8s".equals(sniProperties.getMod())) {
                    TcpSslContextSpec defaultSpec = Objects.requireNonNull(tcpSslContextSpecs.getIfAvailable());
                    server = server.secure(spec -> spec.sslContext(defaultSpec)
                            .setSniAsyncMappings(shenyuSniAsyncMapping), false);
                    shenyuSniAsyncMapping.addSslProvider("shenyu-default", SslProvider.builder().sslContext(defaultSpec).build());
                } else {
                    throw new ShenyuException("Cannot read the sni mod");
                }
            }
            return server;
        }));
        return webServerFactory;
    }

    private static class EventLoopNettyCustomizer implements NettyServerCustomizer {

        private final NettyHttpProperties nettyHttpProperties;

        private final Function<HttpServer, HttpServer> sniProcessor;
    
        /**
         * Instantiates a new Event loop netty customizer.
         *
         * @param nettyHttpProperties the netty tcp config
         */

View on GitHub (pinned to 567142e072)