{"record":{"id":"ac360f98bcde2728","repo":"hibiken/asynq","slug":"handler-not-found-for-task","errorCode":null,"errorMessage":"handler not found for task","messagePattern":"handler not found for task","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"servemux.go","lineNumber":17,"sourceCode":"// Copyright 2020 Kentaro Hibino. All rights reserved.\n// Use of this source code is governed by a MIT license\n// that can be found in the LICENSE file.\n\npackage asynq\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"fmt\"\n\t\"sort\"\n\t\"strings\"\n\t\"sync\"\n)\n\n// ErrHandlerNotFound indicates that no task handler was found for a given pattern.\nvar ErrHandlerNotFound = errors.New(\"handler not found for task\")\n\n// ServeMux is a multiplexer for asynchronous tasks.\n// It matches the type of each task against a list of registered patterns\n// and calls the handler for the pattern that most closely matches the\n// task's type name.\n//\n// Longer patterns take precedence over shorter ones, so that if there are\n// handlers registered for both \"images\" and \"images:thumbnails\",\n// the latter handler will be called for tasks with a type name beginning with\n// \"images:thumbnails\" and the former will receive tasks with type name beginning\n// with \"images\".\ntype ServeMux struct {\n\tmu  sync.RWMutex\n\tm   map[string]muxEntry\n\tes  []muxEntry // slice of entries sorted from longest to shortest.\n\tmws []MiddlewareFunc\n}\n","sourceCodeStart":1,"sourceCodeEnd":35,"githubUrl":"https://github.com/hibiken/asynq/blob/d135f1439bee74e989b7f9b41ecd542cc87f024a/servemux.go#L1-L35","documentation":"ErrHandlerNotFound is a sentinel error indicating that no task handler was registered for the given task type in a ServeMux. The library throws it when a task is dequeued/processed but its type does not match any registered pattern; NotFound wraps the sentinel with the task's quoted type name. Callers can match with errors.Is to distinguish this from handler failures.","triggerScenarios":"Processing (or inspecting) a task whose Type() does not match any pattern registered via ServeMux.Handle/HandleFunc; also returned by ServeMux.NotFoundHandler when invoked. Error is constructed by NotFound() at servemux.go:156.","commonSituations":"Typo in the pattern string vs the task type used at enqueue time; handler registered after the server started processing (race on startup); refactoring task type constants without updating both enqueue and mux registration sides; forgetting to register a handler for tasks enqueued by another service.","solutions":["Register the missing handler for the task type shown in the error via mux.Handle/HandleFunc before calling srv.Run/Start","Compare the quoted type in the error against the string passed to NewTask at enqueue time and fix any mismatch","Use a custom NotFoundHandler / mux.Handle with a catch-all pattern to log unexpected task types during development"],"exampleFix":"// before\nmux.HandleFunc(\"email:welcome\", handleWelcomeEmail)\n// task enqueued as asynq.NewTask(\"email:wellcome\", payload)\n// after\nmux.HandleFunc(\"email:welcome\", handleWelcomeEmail)\n// enqueue with matching type:\nclient.Enqueue(asynq.NewTask(\"email:welcome\", payload))","handlingStrategy":"try-catch","validationCode":"if _, ok := mux.(*asynq.ServeMux); ok {\n    // keep a registry of task types and assert before enqueue\n    if !registeredTypes[taskType] {\n        return fmt.Errorf(\"no handler registered for %q\", taskType)\n    }\n}","typeGuard":null,"tryCatchPattern":"err := task.ProcessTask(ctx, t)\nif err != nil && errors.Is(err, asynq.ErrHandlerNotFound) {\n    log.Printf(\"no handler for task type %q\", t.Type())\n    return asynq.SkipRetry // or DLQ handling\n}","preventionTips":["Define task type strings as shared constants used by both enqueue and mux registration","Add a startup test that enqueues each task type against the mux and asserts no ErrHandlerNotFound","Register all handlers before calling srv.Run/Start"],"tags":["go","task-routing","registration-mismatch"],"backgroundTag":"resource-not-found","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"}