openai/openai-python · error · TypeError

Received positional arguments which are not supported; Keywo

Error message

Received positional arguments which are not supported; Keyword arguments must be used instead

What it means

The build() helper constructs a Pydantic model instance from keyword arguments only. Passing any positional argument is rejected because the SDK cannot reliably map positional values to model fields across schema variations, so it forces explicit keyword usage to avoid silent mis-binding.

Source

Thrown at src/openai/_models.py:572


def build(
    base_model_cls: Callable[P, _BaseModelT],
    *args: P.args,
    **kwargs: P.kwargs,
) -> _BaseModelT:
    """Construct a BaseModel class without validation.

    This is useful for cases where you need to instantiate a `BaseModel`
    from an API response as this provides type-safe params which isn't supported
    by helpers like `construct_type()`.

    ```py
    build(MyModel, my_field_a="foo", my_field_b=123)
    ```
    """
    if args:
        raise TypeError(
            "Received positional arguments which are not supported; Keyword arguments must be used instead",
        )

    return cast(_BaseModelT, construct_type(type_=base_model_cls, value=kwargs))


def construct_type_unchecked(*, value: object, type_: type[_T]) -> _T:
    """Loose coercion to the expected type with construction of nested values.

    Note: the returned value from this function is not guaranteed to match the
    given type.
    """
    return cast(_T, construct_type(value=value, type_=type_))


def construct_type(*, value: object, type_: object, metadata: Optional[List[Any]] = None) -> object:
    """Loose coercion to the expected type with construction of nested values.

View on GitHub (pinned to 9917c6e28e)

Solutions

Pass every field as a keyword argument: build(MyModel, my_field_a='foo', my_field_b=123)
If forwarding dynamic args, unpack them as **kwargs instead of *args

Example fix

// before
build(MyModel, "foo", 123)
// after
build(MyModel, my_field_a="foo", my_field_b=123)

Defensive patterns

Strategy: validation

Validate before calling

def safe_build(model, *args, **kwargs):
    if args:
        raise TypeError(f"{model.__name__} requires keyword arguments: {args}")
    return build(model, **kwargs)

Type guard

def uses_only_kwargs(fn, *args, **kwargs) -> bool:
    return not args

Prevention

Always call build()/construct helpers with explicit keyword arguments
Lint dynamic call sites that forward *args into SDK model helpers

When it happens

Trigger: Calling openai._models.build(MyModel, 'foo', 123) or forwarding *args into build(); any call where the args tuple is non-empty.

Common situations: Copy-pasting pydantic-style MyModel('foo', 123) construction into SDK helper usage; programmatic argument forwarding that accidentally includes positionals.

Related errors

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