{"record":{"id":"c455a5cce2fbf3a4","repo":"hibiken/asynq","slug":"handler-not-set","errorCode":null,"errorMessage":"handler not set","messagePattern":"handler not set","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"processor.go","lineNumber":118,"sourceCode":"\treturn &processor{\n\t\tlogger:            params.logger,\n\t\tbroker:            params.broker,\n\t\tbaseCtxFn:         params.baseCtxFn,\n\t\tclock:             timeutil.NewRealClock(),\n\t\tqueueConfig:       queues,\n\t\torderedQueues:     orderedQueues,\n\t\ttaskCheckInterval: params.taskCheckInterval,\n\t\tretryDelayFunc:    params.retryDelayFunc,\n\t\tisFailureFunc:     params.isFailureFunc,\n\t\tsyncRequestCh:     params.syncCh,\n\t\tcancelations:      params.cancelations,\n\t\terrLogLimiter:     rate.NewLimiter(rate.Every(3*time.Second), 1),\n\t\tsema:              make(chan struct{}, params.concurrency),\n\t\tdone:              make(chan struct{}),\n\t\tquit:              make(chan struct{}),\n\t\tabort:             make(chan struct{}),\n\t\terrHandler:        params.errHandler,\n\t\thandler:           HandlerFunc(func(ctx context.Context, t *Task) error { return fmt.Errorf(\"handler not set\") }),\n\t\tshutdownTimeout:   params.shutdownTimeout,\n\t\tstarting:          params.starting,\n\t\tfinished:          params.finished,\n\t}\n}\n\n// Note: stops only the \"processor\" goroutine, does not stop workers.\n// It's safe to call this method multiple times.\nfunc (p *processor) stop() {\n\tp.once.Do(func() {\n\t\tp.logger.Debug(\"Processor shutting down...\")\n\t\t// Unblock if processor is waiting for sema token.\n\t\tclose(p.quit)\n\t\t// Signal the processor goroutine to stop processing tasks\n\t\t// from the queue.\n\t\tp.done <- struct{}{}\n\t})\n}","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/hibiken/asynq/blob/d135f1439bee74e989b7f9b41ecd542cc87f024a/processor.go#L100-L136","documentation":"This is the placeholder error returned by the processor's default handler when no real Handler was configured on the server. It surfaces at task-processing time: tasks are consumed and immediately fail because the server was created without a handler.","triggerScenarios":"Creating a Server and calling Run/ProcessTasks without SetHandler (or NewServerFromRedisClient/test constructors leaving params.handler nil so newProcessor installs the placeholder). The placeholder HandlerFunc returns fmt.Errorf(\"handler not set\") for every task.","commonSituations":"Forgetting server.SetHandler(mux) before Run; wiring a ServeMux but never assigning it to the server; copy-pasted bootstrap code missing the SetHandler line.","solutions":["Call server.SetHandler(mux) (or set Handler) before starting the server","Verify the handler assignment happens on the same Server instance you Run","Register task types on the mux so tasks match a handler instead of hitting defaults"],"exampleFix":"// before\nsrv.Run(deferred) // handler never set\n// after\nmux := asynq.NewServeMux()\nmux.HandleFunc(\"email:welcome\", welcomeHandler)\nsrv.SetHandler(mux)\nsrv.Run(deferred)","handlingStrategy":"validation","validationCode":"if srvHandler == nil {\n    return errors.New(\"asynq server started without a handler; call SetHandler before Run\")\n}","typeGuard":null,"tryCatchPattern":"// at run time, treat this as fatal config bug\nif err := taskProcessingErr; err != nil && strings.Contains(err.Error(), \"handler not set\") {\n    log.Fatal(\"server misconfigured: no handler set\")\n}","preventionTips":["Always pair Server creation with mux creation and srv.SetHandler(mux) in the same bootstrap function","Add an integration test that runs one task end-to-end to catch missing handlers","Keep bootstrap code in one place to avoid partial setup paths"],"tags":["asynq","handler","setup"],"backgroundTag":"missing-required-config","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"}