openai/openai-python · error · ValueError

fallback is only supported in Pydantic v2

Error message

fallback is only supported in Pydantic v2

What it means

The fallback serialization keyword (Pydantic v2's fallback serializer hook) is unsupported in the Pydantic v1 compat shim of model_dump; any value other than None raises ValueError.

Source

Thrown at src/openai/_models.py:359

                fallback: A function to call when an unknown value is encountered. If not provided,
                    a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError] error is raised.
                serialize_as_any: Whether to serialize fields with duck-typing serialization behavior.

            Returns:
                A dictionary representation of the model.
            """
            if mode not in {"json", "python"}:
                raise ValueError("mode must be either 'json' or 'python'")
            if round_trip != False:
                raise ValueError("round_trip is only supported in Pydantic v2")
            if warnings != True:
                raise ValueError("warnings is only supported in Pydantic v2")
            if context is not None:
                raise ValueError("context is only supported in Pydantic v2")
            if serialize_as_any != False:
                raise ValueError("serialize_as_any is only supported in Pydantic v2")
            if fallback is not None:
                raise ValueError("fallback is only supported in Pydantic v2")
            if exclude_computed_fields != False:
                raise ValueError("exclude_computed_fields is only supported in Pydantic v2")
            dumped = super().dict(  # pyright: ignore[reportDeprecated]
                include=include,
                exclude=exclude,
                by_alias=by_alias if by_alias is not None else False,
                exclude_unset=exclude_unset,
                exclude_defaults=exclude_defaults,
                exclude_none=exclude_none,
            )

            return cast("dict[str, Any]", json_safe(dumped)) if mode == "json" else dumped

        @override
        def model_dump_json(
            self,
            *,
            indent: int | None = None,

View on GitHub (pinned to 9917c6e28e)

Solutions

  1. Remove the fallback argument under Pydantic v1 and handle unsupported values with field serializers or post-processing
  2. Upgrade to pydantic>=2 to use fallback

Example fix

# before
d = obj.model_dump(fallback=fn)
# after
d = obj.model_dump()
Defensive patterns

Strategy: validation

Validate before calling

import pydantic
if pydantic.VERSION.startswith('1.'):
    kwargs.pop('fallback', None)
obj.model_dump(**kwargs)

Prevention

When it happens

Trigger: Calling model.model_dump(fallback=my_serializer) on SDK models under Pydantic v1.

Common situations: Adding a fallback serializer per Pydantic v2 docs while the environment still resolves pydantic v1; mixed dependency pins after a partial upgrade.

Related errors

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/93481d9e9c2363e6. Report an issue: GitHub.