{"record":{"id":"6e2ec6268d9b63fd","repo":"apache/shenyu","slug":"cannot-read-the-sni-mod","errorCode":null,"errorMessage":"Cannot read the sni mod","messagePattern":"Cannot read the sni mod","errorType":"exception","errorClass":"ShenyuException","httpStatus":null,"severity":"error","filePath":"shenyu-spring-boot-starter/shenyu-spring-boot-starter-gateway/src/main/java/org/apache/shenyu/springboot/starter/netty/ShenyuNettyWebServerConfiguration.java","lineNumber":130,"sourceCode":"                            shenyuSniAsyncMapping.addSslCertificate(certificate);\n                        } catch (IOException e) {\n                            LOG.error(\"add certificate error\", e);\n                        }\n                    }\n\n                    SslCrtAndKeyFile defaultCert = certificates.get(0);\n                    TcpSslContextSpec defaultSpec = TcpSslContextSpec.forServer(new File(defaultCert.getKeyCertChainFile()),\n                            new File(defaultCert.getKeyFile()));\n                    \n                    server = server.secure(spec -> spec.sslContext(defaultSpec)\n                                .setSniAsyncMappings(shenyuSniAsyncMapping), false);\n                } else if (\"k8s\".equals(sniProperties.getMod())) {\n                    TcpSslContextSpec defaultSpec = Objects.requireNonNull(tcpSslContextSpecs.getIfAvailable());\n                    server = server.secure(spec -> spec.sslContext(defaultSpec)\n                            .setSniAsyncMappings(shenyuSniAsyncMapping), false);\n                    shenyuSniAsyncMapping.addSslProvider(\"shenyu-default\", SslProvider.builder().sslContext(defaultSpec).build());\n                } else {\n                    throw new ShenyuException(\"Cannot read the sni mod\");\n                }\n            }\n            return server;\n        }));\n        return webServerFactory;\n    }\n\n    private static class EventLoopNettyCustomizer implements NettyServerCustomizer {\n\n        private final NettyHttpProperties nettyHttpProperties;\n\n        private final Function<HttpServer, HttpServer> sniProcessor;\n    \n        /**\n         * Instantiates a new Event loop netty customizer.\n         *\n         * @param nettyHttpProperties the netty tcp config\n         */","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/apache/shenyu/blob/567142e07261b3e615ae8850b30f4421f455cc5d/shenyu-spring-boot-starter/shenyu-spring-boot-starter-gateway/src/main/java/org/apache/shenyu/springboot/starter/netty/ShenyuNettyWebServerConfiguration.java#L112-L148","documentation":"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.","triggerScenarios":"Setting shenyu.server.netty.sni.mod to any value other than 'manual' or 'k8s' (typo, capitalized value, wrong config key spillover).","commonSituations":"Typos like 'Manual', 'kubernetes', or 'auto'; copying mode names from other gateway products; stale config from a version where other modes existed.","solutions":["Change sni.mod to exactly 'manual' or 'k8s'","If you intended Kubernetes secret discovery, use mod: k8s together with the k8s starter","If SNI is not needed, set sni.enabled=false"],"exampleFix":"# before\nsni:\n  enabled: true\n  mod: kubernetes\n# after\nsni:\n  enabled: true\n  mod: k8s","handlingStrategy":"validation","validationCode":"String mod = env.getProperty(\"shenyu.server.netty.sni.mod\");\nif (env.getProperty(\"shenyu.server.netty.sni.enabled\", Boolean.class, false)\n        && !\"manual\".equals(mod) && !\"k8s\".equals(mod)) {\n    throw new IllegalArgumentException(\"sni.mod must be 'manual' or 'k8s', got: \" + mod);\n}","typeGuard":null,"tryCatchPattern":"try {\n    SpringApplication.run(GatewayApplication.class, args);\n} catch (Exception e) {\n    if (rootCauseOf(e, ShenyuException.class).map(x -> x.getMessage().contains(\"Cannot read the sni mod\")).orElse(false)) {\n        log.error(\"Fix shenyu.server.netty.sni.mod to manual|k8s\");\n    } else throw e;\n}","preventionTips":["Whitelist allowed values with a strict enum binding (@EnumValue or custom converter)","Avoid free-text values for mode-like settings","Test startup with each supported sni.mod value"],"tags":["netty","sni","ssl","invalid-enum","configuration"],"backgroundTag":"invalid-enum-value","analyzedSha":"567142e07261b3e615ae8850b30f4421f455cc5d","analyzedAt":"2026-09-12T10:08:21.293Z","contentChangedAt":"2026-09-12T10:08:21.293Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}