openai/openai-python · error · ValueError

mode must be either 'json' or 'python'

Error message

mode must be either 'json' or 'python'

What it means

The SDK's Pydantic v1 compatibility shim for model_dump only accepts mode='json' or mode='python'. Any other mode string (or a typo) is rejected immediately before serialization begins.

Source

Thrown at src/openai/_models.py:349

                by_alias: Whether to use the field's alias in the dictionary key if defined.
                exclude_unset: Whether to exclude fields that have not been explicitly set.
                exclude_defaults: Whether to exclude fields that are set to their default value.
                exclude_none: Whether to exclude fields that have a value of `None`.
                exclude_computed_fields: Whether to exclude computed fields.
                    While this can be useful for round-tripping, it is usually recommended to use the dedicated
                    `round_trip` parameter instead.
                round_trip: If True, dumped values should be valid as input for non-idempotent types such as Json[T].
                warnings: How to handle serialization errors. False/"none" ignores them, True/"warn" logs errors,
                    "error" raises a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError].
                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,

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Use mode='json' for JSON-safe primitives or mode='python' for native objects
2. Omit mode entirely if the default is acceptable

Example fix

# before
d = obj.model_dump(mode='raw')
# after
d = obj.model_dump(mode='json')

mode = kwargs.get('mode', 'python')
assert mode in {'json', 'python'}, f"bad mode: {mode}"

def is_valid_mode(m: str) -> bool:
    return m in {'json', 'python'}

When it happens

Trigger: Calling model.model_dump(mode='json-mode'), mode='' , or any value outside {'json','python'} on any SDK model object (e.g. ChatCompletion, Model).

Common situations: Confusing this API with other libraries' mode names; passing None or an unset config value as mode.

Related errors

• round_trip is only supported in Pydantic v2
• warnings is only supported in Pydantic v2
• context is only supported in Pydantic v2
• fallback is only supported in Pydantic v2
• serialize_as_any is only supported in Pydantic v2

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