openai/openai-python · error · NotImplementedError

Unknown array_format value: {array_format}, choose from {',

Error message

Unknown array_format value: {array_format}, choose from {', '.join(get_args(ArrayFormat))}

What it means

The query-string serializer encountered an array_format option that isn't one of the recognized ArrayFormat literals (comma, repeated, etc.). This is an internal invariant violation: the value came from SDK defaults or user-provided serialization options and didn't match any known format, so NotImplementedError is raised.

Source

Thrown at src/openai/_qs.py:111

                ]
            elif array_format == "repeat":
                items = []
                for item in value:
                    items.extend(self._stringify_item(key, item, opts))
                return items
            elif array_format == "indices":
                items = []
                for i, item in enumerate(value):
                    items.extend(self._stringify_item(f"{key}[{i}]", item, opts))
                return items
            elif array_format == "brackets":
                items = []
                key = key + "[]"
                for item in value:
                    items.extend(self._stringify_item(key, item, opts))
                return items
            else:
                raise NotImplementedError(
                    f"Unknown array_format value: {array_format}, choose from {', '.join(get_args(ArrayFormat))}"
                )

        serialised = self._primitive_value_to_str(value)
        if not serialised:
            return []
        return [(key, serialised)]

    def _primitive_value_to_str(self, value: PrimitiveData) -> str:
        # copied from httpx
        if value is True:
            return "true"
        elif value is False:
            return "false"
        elif value is None:
            return ""
        return str(value)

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Use only documented array_format values from openai._qs.ArrayFormat (e.g. 'comma', 'repeat'/'variables')
2. Update custom serializers after upgrading the SDK
3. Prefer relying on the SDK's default query serializer unless you truly need custom formats

Example fix

// before
QUERY_SERIALIZER = QuerySerializer(array_format="pipes")
// after
QUERY_SERIALIZER = QuerySerializer(array_format="comma")

from openai._qs import ArrayFormat, get_args
assert array_format in get_args(ArrayFormat), f'bad array_format: {array_format}'

from typing import get_args
from openai._qs import ArrayFormat

def is_valid_array_format(value: object) -> bool:
    return isinstance(value, str) and value in get_args(ArrayFormat)

When it happens

Trigger: Passing an invalid array_format via custom qs/options to a request with array query params; SDK version drift where a format literal changed but a stale option value is reused.

Common situations: Hand-constructing QUERY_SERIALIZER or array_format strings; reusing serialization options across SDK major versions after format names changed.

Related errors

• Could not convert data into a valid instance of {type_}
• Pagination is only supported with mappings
• No next page expected; please check `.has_next_page()` befor
• max_retries cannot be None. If you want to disable retries,
• Unexpected JSON data type, {type(json_data)}, cannot merge w

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