{"record":{"id":"344382a03c89aad9","repo":"hibiken/asynq","slug":"asynq-server-cannot-run-with-nil-handler","errorCode":null,"errorMessage":"asynq: server cannot run with nil handler","messagePattern":"asynq: server cannot run with nil handler","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server.go","lineNumber":682,"sourceCode":"\tif err := srv.Start(handler); err != nil {\n\t\treturn err\n\t}\n\tsrv.waitForSignals()\n\tsrv.Shutdown()\n\treturn nil\n}\n\n// Start starts the worker server. Once the server has started,\n// it pulls tasks off queues and starts a worker goroutine for each task\n// and then call Handler to process it.\n// Tasks are processed concurrently by the workers up to the number of\n// concurrency specified in Config.Concurrency.\n//\n// Start returns any error encountered at server startup time.\n// If the server has already been shutdown, ErrServerClosed is returned.\nfunc (srv *Server) Start(handler Handler) error {\n\tif handler == nil {\n\t\treturn fmt.Errorf(\"asynq: server cannot run with nil handler\")\n\t}\n\tsrv.processor.handler = handler\n\n\tif err := srv.start(); err != nil {\n\t\treturn err\n\t}\n\tsrv.logger.Info(\"Starting processing\")\n\n\tsrv.heartbeater.start(&srv.wg)\n\tsrv.healthchecker.start(&srv.wg)\n\tsrv.subscriber.start(&srv.wg)\n\tsrv.syncer.start(&srv.wg)\n\tsrv.recoverer.start(&srv.wg)\n\tsrv.forwarder.start(&srv.wg)\n\tsrv.processor.start(&srv.wg)\n\tsrv.janitor.start(&srv.wg)\n\tsrv.aggregator.start(&srv.wg)\n\treturn nil","sourceCodeStart":664,"sourceCodeEnd":700,"githubUrl":"https://github.com/hibiken/asynq/blob/d135f1439bee74e989b7f9b41ecd542cc87f024a/server.go#L664-L700","documentation":"Server.Start refuses to start the server when the Handler argument is nil. A nil handler means no task-processing function would be available, so tasks could never be executed; asynq fails fast at startup instead of panicking later when a task arrives.","triggerScenarios":"Calling srv.Start(nil), or Start with a variable of interface type Handler whose underlying value is nil (e.g. an uninitialized handler struct pointer assigned to the interface).","commonSituations":"Handler construction failed earlier but the code ignores the error; a factory returns nil on some config path; handler wiring skipped in tests or scaffolding code.","solutions":["Pass a non-nil asynq.Handler (e.g. a valid *asynq.ServeMux or custom handler) to Start.","Check that your handler constructor never returns a nil interface; return an explicit error instead.","Wrap the handler with asynq.HandlerFunc(func(ctx context.Context, t *asynq.Task) error { ... }) if none exists yet."],"exampleFix":"// before\nvar h asynq.Handler\nsrv.Start(h) // h is nil\n// after\nmux := asynq.NewServeMux()\nmux.HandleFunc(\"email:welcome\", handleWelcomeTask)\nsrv.Start(mux)","handlingStrategy":"validation","validationCode":"if handler == nil {\n    return errors.New(\"cannot start asynq server: handler is nil\")\n}\nreturn srv.Start(handler)","typeGuard":"func isNilHandler(h asynq.Handler) bool {\n    return h == nil\n}","tryCatchPattern":"if err := srv.Start(handler); err != nil {\n    log.Fatalf(\"asynq start failed: %v\", err)\n}","preventionTips":["Construct handlers with asynq.NewServeMux() and register tasks before Start.","Check constructor errors immediately so a failed handler never reaches Start.","Add a startup assertion that the handler is non-nil in your server bootstrap function."],"tags":["go","asynq","nil-handler","startup"],"backgroundTag":"null-argument","analyzedSha":"d135f1439bee74e989b7f9b41ecd542cc87f024a","analyzedAt":"2026-09-07T19:02:34.660Z","contentChangedAt":"2026-09-07T19:02:34.660Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}