{"record":{"id":"614eeffc24e7cb10","repo":"apache/shenyu","slug":"can-not-find-shenyusniasyncmapping-bean","errorCode":null,"errorMessage":"Can not find shenyuSniAsyncMapping bean","messagePattern":"Can not find shenyuSniAsyncMapping bean","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":100,"sourceCode":"     * @param shenyuSniAsyncMappingProvider shenyuSniAsyncMapping\n     * @param tcpSslContextSpecs default tcpSslContextSpecs\n     * @return the netty reactive web server factory\n     */\n    @Bean\n    @ConditionalOnProperty(value = \"shenyu.netty.http.web-server-factory-enabled\", havingValue = \"true\", matchIfMissing = true)\n    public NettyReactiveWebServerFactory nettyReactiveWebServerFactory(final ObjectProvider<NettyHttpProperties> properties,\n                                                                       final ObjectProvider<ShenyuSniAsyncMapping> shenyuSniAsyncMappingProvider,\n                                                                       final ObjectProvider<TcpSslContextSpec> tcpSslContextSpecs) {\n        NettyReactiveWebServerFactory webServerFactory = new NettyReactiveWebServerFactory();\n        NettyHttpProperties nettyHttpProperties = Optional.ofNullable(properties.getIfAvailable()).orElse(new NettyHttpProperties());\n        webServerFactory.addServerCustomizers(new EventLoopNettyCustomizer(nettyHttpProperties, httpServer -> {\n            HttpServer server = httpServer;\n            // Configure sni certificates\n            NettyHttpProperties.SniProperties sniProperties = nettyHttpProperties.getSni();\n            if (sniProperties.getEnabled()) {\n                ShenyuSniAsyncMapping shenyuSniAsyncMapping = shenyuSniAsyncMappingProvider.getIfAvailable();\n                if (Objects.isNull(shenyuSniAsyncMapping)) {\n                    throw new ShenyuException(\"Can not find shenyuSniAsyncMapping bean\");\n                }\n                if (\"manual\".equals(sniProperties.getMod())) {\n                    List<SslCrtAndKeyFile> sslCrtAndKeyFiles = sniProperties.getCertificates();\n                    if (CollectionUtils.isEmpty(sslCrtAndKeyFiles)) {\n                        throw new ShenyuException(\"At least one certificate is required\");\n                    }\n\n                    // Use the first certificate as the default certificate (this default certificate will not actually be used)\n                    List<SslCrtAndKeyFile> certificates = sslCrtAndKeyFiles;\n                    for (SslCrtAndKeyFile certificate : certificates) {\n                        try {\n                            shenyuSniAsyncMapping.addSslCertificate(certificate);\n                        } catch (IOException e) {\n                            LOG.error(\"add certificate error\", e);\n                        }\n                    }\n\n                    SslCrtAndKeyFile defaultCert = certificates.get(0);","sourceCodeStart":82,"sourceCodeEnd":118,"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#L82-L118","documentation":"When SNI is enabled (shenyu.server.netty.sni.enabled=true), the Netty web server factory must be supplied with a ShenyuSniAsyncMapping bean that resolves SSL contexts per SNI hostname. If SNI is on but no such bean exists in the context, startup throws this ShenyuException.","triggerScenarios":"Enabling shenyu.server.netty.sni.enabled=true while using 'k8s' (auto-discovery) mode without the shenyu-spring-boot-starter-k8s module (which provides the bean), or the bean was excluded/filtered from component scanning.","commonSituations":"Turning on SNI in a plain gateway deployment that lacks the k8s starter; copying config from a Kubernetes deployment guide into a non-k8s environment; custom build that stripped IngressController auto-configuration.","solutions":["Add the shenyu-spring-boot-starter-k8s dependency which registers the ShenyuSniAsyncMapping bean","Or disable SNI (shenyu.server.netty.sni.enabled=false) if you don't need per-host certificates","Or manually define a ShenyuSniAsyncMapping bean via shenyuSniAsyncMappingProvider-compatible @Bean"],"exampleFix":"// before (pom.xml)\n<!-- only gateway starter -->\n// after\n<dependency>\n  <groupId>org.apache.shenyu</groupId>\n  <artifactId>shenyu-spring-boot-starter-k8s</artifactId>\n  <version>${shenyu.version}</version>\n</dependency>","handlingStrategy":"validation","validationCode":"boolean sniEnabled = env.getProperty(\"shenyu.server.netty.sni.enabled\", Boolean.class, false);\nboolean k8sStarterPresent = ClassUtils.isPresent(\n    \"org.apache.shenyu.springboot.starter.k8s.IngressControllerConfiguration\",\n    ShenyuNettyWebServerConfiguration.class.getClassLoader());\nif (sniEnabled && \"k8s\".equals(env.getProperty(\"shenyu.server.netty.sni.mod\")) && !k8sStarterPresent) {\n    throw new IllegalStateException(\"SNI k8s mode requires the shenyu-spring-boot-starter-k8s module\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    context = SpringApplication.run(GatewayApplication.class, args);\n} catch (Exception e) {\n    if (rootCauseOf(e, ShenyuException.class).map(x -> x.getMessage().contains(\"shenyuSniAsyncMapping\")).orElse(false)) {\n        log.error(\"Enable SNI only with the k8s starter or define a ShenyuSniAsyncMapping bean\");\n    } else throw e;\n}","preventionTips":["Only enable sni.enabled in deployments that include the required SNI provider module","Smoke-test gateway startup in CI with the same SNI flags as production","Document the bean requirement next to the SNI config keys"],"tags":["netty","sni","ssl","missing-bean","spring-boot"],"backgroundTag":"missing-dependency","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"}