Celery Signals user_preload_options docs refer to

The Fix

Updates the user_preload_options signal documentation to replace the deprecated celery.bin.base.Option with click.option, which is the current standard for adding custom CLI options in Celery.

Based on closed celery/celery issue #10026 · 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

@@ -820,22 +820,25 @@ It can be used to add additional command-line arguments to the
 .. code-block:: python
 
-    from celery import Celery
-    from celery import signals
-    from celery.bin.base import Option

repro.py

from celery import Celery
from celery import signals
from click import option

app = Celery()
app.user_options['preload'].add(option(
    '--monitoring', action='store_true',
    help='Enable our external monitoring utility, blahblah',
))

@signals.user_preload_options.connect
def handle_preload_options(options, **kwargs):
    if options['monitoring']:
        enable_monitoring()

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\nUpdates the user_preload_options signal documentation to replace the deprecated celery.bin.base.Option with click.option, which is the current standard for adding custom CLI options in Celery.\nWhen NOT to use: This fix should not be used if the documentation is not updated accordingly.\n\n

Why This Fix Works in Production

Trigger: - [x] I have included all related issues and possible duplicate issues in this issue
Mechanism: The documentation incorrectly referenced a non-existent class, leading to confusion about CLI options

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 referenced a non-existent class, leading to confusion about CLI options
Production symptom (often without a traceback): - [x] I have included all related issues and possible duplicate issues in this issue

Proof / Evidence

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

Discussion

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

Jump to Sources Open on GitHub

“ # Checklist  - [x] I hav”

Issue thread · issue description · source

Failure Signature (Search String)

- [x] I have included all related issues and possible duplicate issues in this issue
or possible duplicates to this issue as requested by the checklist above.

Copy-friendly signature

signature.txt

Failure Signature
-----------------
- [x] I have included all related issues and possible duplicate issues in this issue
or possible duplicates to this issue as requested by the checklist above.

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
- [x] I have included all related issues and possible duplicate issues in this issue
or possible duplicates to this issue as requested by the checklist above.

Minimal Reproduction

repro.py

from celery import Celery
from celery import signals
from click import option

app = Celery()
app.user_options['preload'].add(option(
    '--monitoring', action='store_true',
    help='Enable our external monitoring utility, blahblah',
))

@signals.user_preload_options.connect
def handle_preload_options(options, **kwargs):
    if options['monitoring']:
        enable_monitoring()

What Broke

Users encountered errors when trying to use non-existent CLI options in the documentation.

Why It Broke

The documentation incorrectly referenced a non-existent class, leading to confusion about CLI options

Fix Options (Details)

Option A — Apply the official fix

Updates the user_preload_options signal documentation to replace the deprecated celery.bin.base.Option with click.option, which is the current standard for adding custom CLI options in Celery.

When NOT to use: This fix should not be used if the documentation is not updated accordingly.

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

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

When NOT to Use This Fix

This fix should not be used if the documentation is not updated accordingly.

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.

Celery Signals user_preload_options docs refer to non-existent celery.bin.base.Option (Fix)