openai/openai-python · error · TypeError

Unexpected list delta entry is not a dictionary: {delta_entr

Error message

Unexpected list delta entry is not a dictionary: {delta_entry}

What it means

Raised inside accumulate_delta when a list-valued delta contains an entry that is not a dict. List deltas are merged by index and each entry is expected to be a dictionary carrying an index key; anything else (string, number, nested list) hits this TypeError. The duplicated logic also exists in _deltas.py used by the Chat/Responses accumulators, so the same payload shape triggers it in both places.

Source

Thrown at src/openai/lib/streaming/_assistants.py:1019

            acc[key] = delta_value
            continue

        if isinstance(acc_value, str) and isinstance(delta_value, str):
            acc_value += delta_value
        elif isinstance(acc_value, (int, float)) and isinstance(delta_value, (int, float)):
            acc_value += delta_value
        elif is_dict(acc_value) and is_dict(delta_value):
            acc_value = accumulate_delta(acc_value, delta_value)
        elif is_list(acc_value) and is_list(delta_value):
            # for lists of non-dictionary items we'll only ever get new entries
            # in the array, existing entries will never be changed
            if all(isinstance(x, (str, int, float)) for x in acc_value):
                acc_value.extend(delta_value)
                continue

            for delta_entry in delta_value:
                if not is_dict(delta_entry):
                    raise TypeError(f"Unexpected list delta entry is not a dictionary: {delta_entry}")

                try:
                    index = delta_entry["index"]
                except KeyError as exc:
                    raise RuntimeError(f"Expected list delta entry to have an `index` key; {delta_entry}") from exc

                if not isinstance(index, int):
                    raise TypeError(f"Unexpected, list delta entry `index` value is not an integer; {index}")

                try:
                    acc_entry = acc_value[index]
                except IndexError:
                    acc_value.insert(index, delta_entry)
                else:
                    if not is_dict(acc_entry):
                        raise TypeError("not handled yet")

                    acc_value[index] = accumulate_delta(acc_entry, delta_entry)

View on GitHub (pinned to 9917c6e28e)

Solutions

  1. Upgrade (or align) the openai SDK to the version matching the API schema you are streaming from
  2. If you build deltas yourself, ensure list entries are dicts containing an integer index key
  3. Report the payload shape to OpenAI if it occurs against a stable, current SDK
  4. As a stopgap, catch TypeError around accumulation and fall back to replacing the list

Example fix

# before
result = accumulate_delta(acc, delta)  # raises TypeError on scalar entries

# after
try:
    result = accumulate_delta(acc, delta)
except TypeError:
    result = copy.deepcopy(delta)  # replace wholesale as fallback
Defensive patterns

Strategy: validation

Validate before calling

def delta_entries_valid(delta_value) -> bool:
    return all(isinstance(e, dict) for e in delta_value) or all(
        isinstance(e, (str, int, float)) for e in delta_value
    )

Type guard

def is_scalar_list(value: list) -> bool:
    return all(isinstance(x, (str, int, float)) for x in value)

Try / catch

try:
    acc = accumulate_delta(acc, delta)
except TypeError:
    acc[key] = copy.deepcopy(delta)  # replace list wholesale

Prevention

When it happens

Trigger: Streaming responses where a list field delta (e.g. annotations, content parts) contains scalar entries: after the first merge pass appends str/int/float scalars, subsequent dict entries in delta_value reach the per-entry check; or server payloads with unexpected list shapes during active development of streaming APIs.

Common situations: Using pre-release Responses/Assistants streaming endpoints whose delta schemas changed between SDK and API versions; SDK version lag behind API schema additions; manually constructed delta payloads in tests.

Related errors

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