Celery已注册任务运行时报Received unregistered task类型KeyError如何解决

• 核心原因是任务调用名称与注册名称不匹配：你提到注册的任务路径为myapp.tasks.my_task（应用名无下划线），但报错日志中Celery尝试加载的任务路径是my_app.tasks.my_task（应用名多了下划线），二者不一致导致Celery判定任务未注册。
• 同模块其他任务可正常运行，说明其余任务的调用路径与注册路径完全对齐，仅my_task的调用代码存在路径填写错误，或存在隐藏的导入别名配置问题。
• 少见场景：你近期修改过my_task的定义或所属模块，worker进程未重启加载新配置，旧的注册缓存导致匹配失败，不过该场景通常会影响同模块所有任务，和你描述的现象契合度较低。

1. 核对任务调用路径 #

找到调用my_task的代码，根据调用方式排查错误：
如果是直接导入任务对象调用，检查导入路径是否与实际模块路径一致：

# 错误导入（应用名多了下划线）
from my_app.tasks import my_task
my_task.delay()

# 正确导入（与实际模块名完全匹配）
from myapp.tasks import my_task
my_task.delay()

如果是通过字符串指定任务名调用，需与注册的任务名完全对齐：

# 错误写法
app.send_task('my_app.tasks.my_task')

# 正确写法
app.send_task('myapp.tasks.my_task')

2. 显式指定任务名避免路径歧义 #

Celery默认会使用「模块路径+函数名」自动生成任务名，你可以在任务装饰器中显式指定任务名，彻底规避路径匹配问题：

@shared_task(queue='celery', name='my_custom_task_name')
def my_task():
   """ 自定义任务名后不再依赖模块路径匹配 """
   ...

调用时直接使用指定的名称即可：

app.send_task('my_custom_task_name')

3. 重启worker清除缓存 #

如果核对路径后确认完全一致仍然报错，执行以下命令重启worker进程，清除旧的注册缓存即可：

# 停止原有worker进程后重新启动
celery -A your_celery_app_name worker -l info

你也可以重新执行celery inspect registered命令，确认my_task的完整注册名称，和调用时的名称完全对齐即可解决问题。

内容的提问来源于stack exchange，提问作者Ashkan Khademian