Celery CELERY_TASK_DEFAULT_QUEUE is wrong (Fix)

The Fix

Fixes the documentation for CELERY_TASK_ settings to clarify the correct usage of uppercase settings in Celery.

Based on closed celery/celery issue #5575 · PR/commit linked

Production note: This usually shows up under retries/timeouts. Treat it as a side-effect risk until you can verify behavior with a canary + real traffic.

Jump to Verify Open PR/Commit

@@ -109,24 +109,24 @@ rush in moving to the new settings format.
 ``CELERY_SECURITY_CERT_STORE``         :setting:`security_cert_store`
 ``CELERY_SECURITY_KEY``                :setting:`security_key`
-``CELERY_ACKS_LATE``                   :setting:`task_acks_late`
+``CELERY_TASK_ACKS_LATE``              :setting:`task_acks_late`
 ``CELERY_TASK_ALWAYS_EAGER``           :setting:`task_always_eager`

repro.py

from celery import Celery


class BaseConfig:
    BROKER_URL = 'redis://localhost:6379/0'
    CELERY_TASK_DEFAULT_QUEUE = 'test'

celery_app = Celery()
celery_app.config_from_object(BaseConfig)

@celery_app.task
def simple_task():
    raise Exception("Testing Celery exception")

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

fix.md

Option A — Apply the official fix\nFixes the documentation for CELERY_TASK_ settings to clarify the correct usage of uppercase settings in Celery.\nWhen NOT to use: Do not use if it changes public behavior or if the failure cannot be reproduced.\n\n

Why This Fix Works in Production

Trigger: - [x] I have included all related issues and possible duplicate issues
Mechanism: The documentation incorrectly lists CELERY_TASK_DEFAULT_QUEUE as a valid setting, causing confusion

Production impact:

If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.

Why This Breaks in Prod

The documentation incorrectly lists CELERY_TASK_DEFAULT_QUEUE as a valid setting, causing confusion
Production symptom (often without a traceback): - [x] I have included all related issues and possible duplicate issues

Proof / Evidence

GitHub issue: #5575
Fix PR: https://github.com/celery/celery/pull/4094
Reproduced locally: No (not executed)
Last verified: 2026-02-11
Confidence: 0.60
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.60

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“thanks for the detailed report! can you come up with code n doc fixes?”

@auvipy · 2019-06-09 · source

“@okomarov For what it is worth, you can just take the "new" settings names and capitalize them and it works fine. This is what we…”

@clokep · 2019-06-12 · source

“@auvipy Very tight on time but would try. Is there a centralized place where old setting names are converted to the new ones, or can…”

@okomarov · 2019-06-11 · source

“Taking a look at the code this seems to be correct (as task_default_queue), see https://github.com/celery/celery/blob/49f6b572e571bcb5b668ce3d25507668c877102f/celery/app/defaults.py#L259 The old setting was CELERY_TASK_DEFAULT_QUEUE, the new is task_default_qu”

@clokep · 2019-06-11 · source

Failure Signature (Search String)

- [x] I have included all related issues and possible duplicate issues
raise Exception("Testing Celery exception")

Copy-friendly signature

signature.txt

Failure Signature
-----------------
- [x] I have included all related issues and possible duplicate issues
raise Exception("Testing Celery exception")

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
- [x] I have included all related issues and possible duplicate issues
raise Exception("Testing Celery exception")

Minimal Reproduction

repro.py

from celery import Celery


class BaseConfig:
    BROKER_URL = 'redis://localhost:6379/0'
    CELERY_TASK_DEFAULT_QUEUE = 'test'

celery_app = Celery()
celery_app.config_from_object(BaseConfig)

@celery_app.task
def simple_task():
    raise Exception("Testing Celery exception")

What Broke

Users experience misconfiguration issues leading to tasks not being queued correctly.

Why It Broke

The documentation incorrectly lists CELERY_TASK_DEFAULT_QUEUE as a valid setting, causing confusion

Fix Options (Details)

Option A — Apply the official fix

Fixes the documentation for CELERY_TASK_ settings to clarify the correct usage of uppercase settings in Celery.

When NOT to use: Do not use if it changes public behavior or if the failure cannot be reproduced.

Fix reference: https://github.com/celery/celery/pull/4094

Last verified: 2026-02-11. Validate in your environment.

When NOT to Use This Fix

Do not use if it changes public behavior or if the failure cannot be reproduced.

Verify Fix

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Capture the exact failing error string in logs and tests so you can reproduce via a minimal script.
Pin production dependencies and upgrade only with a reproducible test that hits the failing path.

Related Issues

No related fixes found.

Cluster: celery:configuration-error Celery hub Celery best practices All hubs All clusters

Related clusters: Data consistency Duplicates Duplicate processing

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.