Celery Adding support for pydantic model serialization (Fix)

The Fix

pip install celery==5.5.0

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

@@ -1,8 +1,11 @@
@@ -1,8 +1,11 @@
 """Actual App instance implementation."""
+import functools
+import importlib
 import inspect

repro.py

from inspect import signature
from celery import Task, Celery


class BaseTask(Task):
    def __call__(self, *args, **kwargs):
        sig = signature(self.__wrapped__)
        bound_args = sig.bind(*args, **kwargs)
        for arg_name, arg_value in bound_args.arguments.items():
            if arg_name in self.__wrapped__.__annotations__:
                typehint = self.__wrapped__.__annotations__[arg_name]
                if not isinstance(arg_value, typehint):
                    raise ValueError(f"Argument {arg_name} is not of type {typehint}")
        result = super(BaseTask, self).__call__(*args, **kwargs)
        return result

    def on_success(self, retval, task_id, args, kwargs):
        super(BaseTask, self).on_success(retval, task_id, args, kwargs)

    def on_failure(self, exc, task_id, args, kwargs, einfo):
        super(BaseTask, self).on_failure(exc, task_id, args, kwargs, einfo)
        
app = Celery(...)
app.Task = BaseTask

verify

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

fix.md

Option A — Upgrade to fixed release\npip install celery==5.5.0\nWhen NOT to use: This fix should not be used if Pydantic is not installed or if strict validation is not desired.\n\n

Why This Fix Works in Production

Trigger: kombu.exceptions.EncodeError: Object of type QBotMessage is not JSON serializable
Mechanism: The lack of support for Pydantic model serialization in Celery tasks caused serialization errors
Why the fix works: Adds support for Pydantic model validation and serialization in Celery tasks, allowing for automatic data validation and safer typing. (first fixed release: 5.5.0).

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

Dependency interaction matters here: Pydantic v2.
Shows up under Python 3.12 in real deployments (not just unit tests).
The lack of support for Pydantic model serialization in Celery tasks caused serialization errors
Surfaces as: kombu.exceptions.EncodeError: Object of type QBotMessage is not JSON serializable

Proof / Evidence

GitHub issue: #8751
Fix PR: https://github.com/celery/celery/pull/9023
First fixed release: 5.5.0
Reproduced locally: No (not executed)
Last verified: 2026-02-09
Confidence: 0.75
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.33

Discussion

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

Jump to Sources Open on GitHub

“I tried out @badge's solution and it inspired me to make my own solution to work for my use case”

@martinkozle · 2024-02-17 · source

“I'm very keen to try out this feature, and checked the document for an example”

@dcsan · 2024-08-12 · confirmation · source

“Looking at this more closely today, I believe this is not really possible just with Celery Serializers as they are now”

@mathiasertl · 2024-05-06 · source

“I got a rudimentary solution to this working: https://gist.github.com/badge/926165ff21ce438c8ddb58aba87021e0”

@badge · 2024-02-09 · source

Failure Signature (Search String)

kombu.exceptions.EncodeError: Object of type QBotMessage is not JSON serializable

Error Message

Stack trace

error.txt

Error Message
-------------
kombu.exceptions.EncodeError: Object of type QBotMessage is not JSON serializable

Stack trace

error.txt

Error Message
-------------
File "/Users/dc/dev/proj/tealbook/voyager/.venv/lib/python3.12/site-packages/kombu/serialization.py", line 220, in dumps
    payload = encoder(data)
              ^^^^^^^^^^^^^
  File "/Users/dc/dev/proj/tealbook/voyager/.venv/lib/python3.12/site-packages/kombu/utils/json.py", line 63, in dumps
    return _dumps(s, cls=cls, **dict(default_kwargs, **kwargs))
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/Cellar/[email protected]/3.12.3/Frameworks/Python.framework/Versions/3.12/lib/python3.12/json/__init__.py", line 238, in dumps
    **kw).encode(obj)
          ^^^^^^^^^^^
  File "/opt/homebrew/Cellar/[email protected]/3.12.3/Frameworks/Python.framework/Versions/3.12/lib/python3.12/json/encoder.py", line 200, in encode
    chunks = self.iterencode(o, _one_shot=True)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/Cellar/[email protected]/3.12.3/Frameworks/Python.framework/Versions/3.12/lib/python3.12/json/encoder.py", line 258, in iterencode
    return _iterencode(o, 0)
           ^^^^^^^^^^^^^^^^^
  File "/Users/dc/dev/proj/tealbook/voyager/.venv/lib/python3.12/site-packages/kombu/utils/json.py", line 47, in default
    return super().default(o)
           ^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/Cellar/[email protected]/3.12.3/Frameworks/Python.framework/Versions/3.12/lib/python3.12/json/encoder.py", line 180, in default
    raise TypeError(
... (truncated) ...

Minimal Reproduction

repro.py

from inspect import signature
from celery import Task, Celery


class BaseTask(Task):
    def __call__(self, *args, **kwargs):
        sig = signature(self.__wrapped__)
        bound_args = sig.bind(*args, **kwargs)
        for arg_name, arg_value in bound_args.arguments.items():
            if arg_name in self.__wrapped__.__annotations__:
                typehint = self.__wrapped__.__annotations__[arg_name]
                if not isinstance(arg_value, typehint):
                    raise ValueError(f"Argument {arg_name} is not of type {typehint}")
        result = super(BaseTask, self).__call__(*args, **kwargs)
        return result

    def on_success(self, retval, task_id, args, kwargs):
        super(BaseTask, self).on_success(retval, task_id, args, kwargs)

    def on_failure(self, exc, task_id, args, kwargs, einfo):
        super(BaseTask, self).on_failure(exc, task_id, args, kwargs, einfo)
        
app = Celery(...)
app.Task = BaseTask

Environment

Python: 3.12
Pydantic: 2

What Broke

Users experienced serialization errors when passing Pydantic models as task arguments.

Why It Broke

The lack of support for Pydantic model serialization in Celery tasks caused serialization errors

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

pip install celery==5.5.0

When NOT to use: This fix should not be used if Pydantic is not installed or if strict validation is not desired.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

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

First fixed release: 5.5.0

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

When NOT to Use This Fix

This fix should not be used if Pydantic is not installed or if strict validation is not desired.

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.

Version Compatibility Table

Version	Status
5.5.0	Fixed

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.