openai/openai-python · error · RuntimeError

Expected list delta entry to have an `index` key; {delta_ent

Error message

Expected list delta entry to have an `index` key; {delta_entry}

What it means

Raised by accumulate_delta in _deltas.py when a list delta entry is a dict missing the required 'index' key; the KeyError is converted into this descriptive RuntimeError. The index key is how the accumulator locates the accumulated entry to merge into.

Source

Thrown at src/openai/lib/streaming/_deltas.py:47

        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)

        acc[key] = acc_value

    return acc

View on GitHub (pinned to 9917c6e28e)

Solutions

  1. Upgrade the openai package
  2. Add an integer index to each list delta entry you construct
  3. Pin compatible API/SDK versions during beta windows
  4. Wrap accumulation in try/except RuntimeError with list replacement fallback

Example fix

# before
entry = {"text": "hi"}

# after
entry = {"index": 0, "text": "hi"}
Defensive patterns

Strategy: validation

Validate before calling

def entries_indexed(entries) -> bool:
    return all(isinstance(e, dict) and "index" in e for e in entries)

Type guard

def is_indexed_delta_entry(entry) -> bool:
    return isinstance(entry, dict) and "index" in entry

Try / catch

try:
    acc = accumulate_delta(acc, delta)
except RuntimeError:
    acc[key] = copy.deepcopy(delta[key])

Prevention

When it happens

Trigger: Chat/Responses streaming deltas whose list entries omit index; API/SDK schema drift; manually crafted delta objects missing the key.

Common situations: Beta endpoint schema evolution; stale SDK pins; fixtures written against outdated docs.

Related errors

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