Celery — Received unregistered task of type error

Fix Celery "unregistered task" by ensuring workers import the module that defines the task and use the same app and name.

intermediatedebuggingpythoncelery

Symptoms

Received unregistered task of type "app.tasks.foo"
The producer sends the task but the worker never processes it
The task works when called locally but fails when sent to the worker
Changing the task name breaks routing after deployment

Possible causes

The worker process did not import the module where the task is defined
The producer and worker use different Celery apps or brokers
An explicit task name changed while messages still carry the old name
Autodiscovery is not configured so the worker never loads the module

Diagnosis steps

List tasks the worker knows

celery -A app inspect registered

Interpretation

If the failing task is absent, the worker never imported its module. If present, the name or queue differs.

Confirm the worker imports the module

celery -A app worker -l info --concurrency 1

Interpretation

Startup logs list imported task modules. Missing modules reveal an autodiscovery or import path problem.

Compare producer and worker app configuration

grep -rn "Celery(" app/ && grep -rn "broker_url\|task_queues" app/config.py

Interpretation

Divergent broker URLs, queue names or task names mean messages go where no worker listens or carry unknown names.

Root cause

The message references a task name that the worker has not registered because its module was never imported, or the producer and worker disagree on the app, queue or explicit task name.

Fix

Make the worker import the task modules through include or autodiscover, and align the app, broker, queue and task names between producer and worker. Deploy worker and producer together when names change.

Verify the fix

Send a test task and confirm the worker executes it and logs the result, then rerun the inspect registered command and confirm the task appears.

Symptom walkthrough

A task is published successfully but the worker logs Received unregistered task of type and discards it. Calling the same function in a local shell works, which hides the problem because that process imported the module. The failure typically appears after deploying a code change or after separating producer and worker configurations.

Fix in practice

Ensure the worker imports every module that defines tasks, using autodiscover or an explicit include list, and keep the broker, queue and task names identical between producer and worker. When you rename a task, deploy both sides together, since in-flight messages carry the old name.

Verification

Publish a test task and confirm the worker logs and completes it, then run the registered-tasks inspection to confirm the name is known. A task that appears in the list and runs successfully confirms the wiring is correct.

Diagnostic commands

Check the behavior with commands like these:

celery -A app inspect registered
celery -A app worker -l info --concurrency 1
grep -rn "Celery(" app/ && grep -rn "broker_url\|task_queues" app/config.py