openai/openai-python · warning · 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

When the SDK serializes sequences for multipart/form-data uploads it computes a per-item field-name suffix based on the configured ArrayFormat ('indices', 'repeat', or 'comma'). _array_suffix raises NotImplementedError when it receives any other value, which in practice cannot happen through public APIs — it guards the internal contract. Seeing it means custom code invoked the transform internals with an array_format string outside the allowed set.

Source

Thrown at src/openai/_utils/_utils.py:74

    Note: this mutates the given dictionary.
    """
    files: list[tuple[str, FileTypes]] = []
    for path in paths:
        files.extend(_extract_items(query, path, index=0, flattened_key=None, array_format=array_format))
    return files


def _array_suffix(array_format: ArrayFormat, array_index: int) -> str:
    if array_format == "brackets":
        return "[]"
    if array_format == "indices":
        return f"[{array_index}]"
    if array_format == "repeat" or array_format == "comma":
        # Both repeat the bare field name for each file part; there is no
        # meaningful way to comma-join binary parts.
        return ""
    raise NotImplementedError(
        f"Unknown array_format value: {array_format}, choose from {', '.join(get_args(ArrayFormat))}"
    )


def _extract_items(
    obj: object,
    path: Sequence[str],
    *,
    index: int,
    flattened_key: str | None,
    array_format: ArrayFormat,
) -> list[tuple[str, FileTypes]]:
    try:
        key = path[index]
    except IndexError:
        if not is_given(obj):
            # no value was provided - we can safely ignore
            return []

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Use only the documented ArrayFormat literal values: 'indices', 'repeat', 'comma'
2. Avoid calling private transform helpers directly; construct uploads through the public client methods
3. Fix typos in the array_format variable feeding the transform
4. If patching in tests, patch with one of the real literals

Example fix

# before
_array_suffix(item, array_format="brackets", array_index=0)

# after
from openai._utils import _array_suffix
_array_suffix(item, array_format="indices", array_index=0)

from typing import get_args
from openai._utils._utils import ArrayFormat  # adjust import
assert fmt in get_args(ArrayFormat), f"bad format {fmt}"

def is_valid_array_format(v: str) -> bool:
    return v in {"indices", "repeat", "comma"}

try:
    serialize(items, fmt)
except NotImplementedError:
    fmt = "indices"; serialize(items, fmt)

When it happens

Trigger: Calling the SDK's internal multipart transform utilities directly with array_format set to something other than the literal values of ArrayFormat (e.g. 'brackets' or a translated/localized copy); monkeypatching internals during tests with an invalid constant.

Common situations: Test code patching serialization internals; forks or copy-pasted transform code drifting from the original; passing a variable that shadowed the ArrayFormat literal with a typo.

Related errors

• Passing both `body` and `content` is not supported
• mode must be either 'json' or 'python'
• round_trip is only supported in Pydantic v2
• warnings is only supported in Pydantic v2
• context is only supported in Pydantic v2

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