{"record":{"id":"70b4a3c0356d28a0","repo":"micro/go-micro","slug":"failed-to-register-handlers-w","errorCode":null,"errorMessage":"failed to register handlers: %w","messagePattern":"failed to register handlers: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gateway/api/gateway.go","lineNumber":72,"sourceCode":"\t\topts.Address = \":8080\"\n\t}\n\tif opts.Context == nil {\n\t\topts.Context = context.Background()\n\t}\n\tif opts.Logger == nil {\n\t\topts.Logger = log.Default()\n\t}\n\tif opts.Registry == nil {\n\t\topts.Registry = registry.DefaultRegistry\n\t}\n\n\t// Create a new mux for this gateway instance\n\tmux := http.NewServeMux()\n\n\t// Register handlers using the provided registrar\n\tif opts.HandlerRegistrar != nil {\n\t\tif err := opts.HandlerRegistrar(mux); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to register handlers: %w\", err)\n\t\t}\n\t}\n\n\t// Create HTTP server\n\tserver := &http.Server{\n\t\tAddr:    opts.Address,\n\t\tHandler: mux,\n\t}\n\n\tgw := &Gateway{\n\t\topts:   opts,\n\t\tserver: server,\n\t\tmux:    mux,\n\t}\n\n\t// Start server in background\n\tgo func() {\n\t\topts.Logger.Printf(\"[gateway] Listening on %s (auth: %v)\", opts.Address, opts.AuthEnabled)","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/micro/go-micro/blob/24529f140421a11a33b6999ab7944f2021cfd69c/gateway/api/gateway.go#L54-L90","documentation":"New wraps any error returned by the caller-provided opts.HandlerRegistrar while it registers HTTP handlers on the gateway's mux. The gateway itself cannot start without its handlers, so the registration failure aborts construction with this wrapped message.","triggerScenarios":"Calling gateway/api.New (directly or via StartGateway/Run) with opts.HandlerRegistrar set to a function that returns an error, e.g. because one of the registered handlers panics-free checks fail or a dependency is missing.","commonSituations":"Custom registrar wiring routes that depend on an uninitialized service or bad config; a registrar that returns an error for a duplicate route pattern; nil dependencies captured by the registrar closure.","solutions":["Inspect the wrapped (%w) inner error from your HandlerRegistrar; fix the underlying cause there.","Validate all dependencies the registrar needs (config, clients) before calling New.","Temporarily replace the registrar with a no-op to confirm the failure originates in your handler registration code."],"exampleFix":"// before\nregistrar := func(mux *http.ServeMux) error { return svc.Handler() } // Handler may be nil\n// after\nif svc.Handler == nil { return errors.New(\"handler not initialized\") }\nregistrar := func(mux *http.ServeMux) error { return svc.Handler() }","handlingStrategy":"try-catch","validationCode":"if opts.HandlerRegistrar != nil {\n    // dry-run against a throwaway mux to surface registration errors early\n    if err := opts.HandlerRegistrar(http.NewServeMux()); err != nil {\n        return fmt.Errorf(\"registrar failed pre-flight: %w\", err)\n    }\n}","typeGuard":null,"tryCatchPattern":"gw, err := api.New(cfg, opts)\nif err != nil {\n    var regErr error\n    if strings.Contains(err.Error(), \"failed to register handlers\") {\n        log.Fatalf(\"handler registrar failed: %v\", errors.Unwrap(err))\n    }\n    return err\n}","preventionTips":["Ensure all handler dependencies are initialized before New.","Unit-test your HandlerRegistrar in isolation.","Avoid duplicate route patterns on the mux.","Keep the registrar side-effect free other than mux registration."],"tags":["http","gateway","startup","handler-registration"],"backgroundTag":"handler-registration-failed","analyzedSha":"24529f140421a11a33b6999ab7944f2021cfd69c","analyzedAt":"2026-09-01T02:52:24.923Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}