{"record":{"id":"5b2034056647bca7","repo":"kubesphere/kubesphere","slug":"failed-to-build-handler-chain-v","errorCode":null,"errorMessage":"failed to build handler chain: %v","messagePattern":"failed to build handler chain: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/apiserver/apiserver.go","lineNumber":135,"sourceCode":"\ts.container.RecoverHandler(func(panicReason interface{}, httpWriter http.ResponseWriter) {\n\t\tlogStackOnRecover(panicReason, httpWriter)\n\t})\n\ts.installDynamicResourceAPI()\n\ts.installKubeSphereAPIs()\n\ts.installMetricsAPI()\n\ts.installHealthz()\n\ts.installLivez()\n\tif err := s.installOpenAPI(); err != nil {\n\t\treturn err\n\t}\n\n\tfor _, ws := range s.container.RegisteredWebServices() {\n\t\tklog.V(2).Infof(\"%s\", ws.RootPath())\n\t}\n\n\tcombinedHandler, err := s.buildHandlerChain(s.container, stopCh)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to build handler chain: %v\", err)\n\t}\n\ts.Server.Handler = filters.WithGlobalFilter(combinedHandler)\n\treturn nil\n}\n\nfunc (s *APIServer) installOpenAPI() error {\n\ts.OpenAPIConfig = &restfulspec.Config{\n\t\tWebServices:                   s.container.RegisteredWebServices(),\n\t\tPostBuildSwaggerObjectHandler: openapicontroller.EnrichSwaggerObject,\n\t}\n\n\topenapiV2Services, err := openapiv2.BuildAndRegisterAggregator(s.OpenAPIConfig, s.container)\n\tif err != nil {\n\t\tklog.Errorf(\"failed to install openapi v2 service : %s\", err)\n\t}\n\ts.openAPIV2Service = openapiV2Services\n\topenapiV3Services, err := openapiv3.BuildAndRegisterAggregator(s.OpenAPIConfig, s.container)\n\tif err != nil {","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/kubesphere/kubesphere/blob/04a29b5c601470fa6bc2f2e92358dcb802a0d414/pkg/apiserver/apiserver.go#L117-L153","documentation":"During APIServer PrepareRun, the server assembles its full HTTP handler chain via buildHandlerChain (authn/authz, filters, auditing, etc.). If that assembly returns an error, PrepareRun wraps and re-raises it as 'failed to build handler chain', aborting server startup before it can serve requests.","triggerScenarios":"Calling APIServer.PrepareRun (during ks-apiserver startup) when buildHandlerChain fails, typically due to a misconfigured or unloadable dependency in the chain: invalid options (bad TLS/authn/authz settings, invalid insecure/port config), failure constructing an auditing or authentication filter, or an error initializing a registered filter dependency.","commonSituations":"Invalid ks-apiserver.yaml options (e.g., wrong client secret/oauth options, bad TLS cert paths); auditing backend misconfiguration (bad webhook/elasticsearch URL); identity provider or token authenticator misconfiguration; version-upgrade leaving stale option keys in the ConfigMap.","solutions":["Read the wrapped inner error in the log (%v payload) — it names the actual failing component; fix that configuration first.","Validate the ks-apiserver ConfigMap/options: check TLS certs/keys, authentication (oauthOptions, identity providers), authorization, and auditing settings for syntactic and semantic correctness.","Verify external dependencies referenced by the handler chain (webhook URLs, Redis/DB for auditing/session, token issuers) are reachable and correctly configured.","If introduced after an upgrade, diff the options against the release's sample configuration and remove/rename deprecated keys.","Reproduce with klog verbosity raised (klog.V(2) shows web services/handler setup) to pinpoint which chain component errors."],"exampleFix":"// before (ks-apiserver.yaml): bad cert path\nsecretReference:\n  tlsCertFile: /etc/kubesphere/tls.crt\n// after\nsecretReference:\n  tlsCertFile: /etc/kubesphere/certs/tls.crt\n// and ensure the file exists before starting the server","handlingStrategy":"validation","validationCode":"// pre-flight config check before starting the server\nfor _, f := range []string{tlsCertFile, tlsKeyFile} {\n    if _, err := os.Stat(f); err != nil {\n        return fmt.Errorf(\"missing required file %s: %w\", f, err)\n    }\n}\nif _, err := url.Parse(auditWebhookURL); err != nil {\n    return fmt.Errorf(\"invalid audit webhook url: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := server.PrepareRun(stopCh); err != nil {\n    klog.Fatalf(\"apiserver prepare failed: %v\", err) // inspect wrapped inner error for the failing component\n}","preventionTips":["Validate the ks-apiserver ConfigMap against the release's sample config in CI (schema/lint check).","Pre-flight check cert/key file paths and external dependency URLs before restart.","Pin and diff configuration across upgrades to catch deprecated option keys.","Enable klog V(2)+ in staging environments to trace handler chain construction."],"tags":["apiserver","startup","handler-chain","configuration"],"backgroundTag":"server-startup-configuration-error","analyzedSha":"04a29b5c601470fa6bc2f2e92358dcb802a0d414","analyzedAt":"2026-09-03T18:33:15.017Z","contentChangedAt":"2026-09-03T18:33:15.017Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}