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 inside accumulate_delta when a list delta entry is a dict but has no 'index' key. Indexed list merging needs index to know where to place/merge the entry; its absence (KeyError) is converted to this RuntimeError with the offending entry in the message.

Source

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

        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. Update the openai package to the latest release matching the API
  2. Include an integer index key in every list delta entry you construct
  3. Pin to known-compatible API/SDK versions during beta periods
  4. Catch RuntimeError and fall back to whole-list replacement if resilient accumulation is required

Example fix

# before
entry = {"type": "output_text", "text": "hi"}  # no index
acc = accumulate_delta(acc, {"content": [entry]})

# after
entry = {"index": 0, "type": "output_text", "text": "hi"}
acc = accumulate_delta(acc, {"content": [entry]})
Defensive patterns

Strategy: validation

Validate before calling

def entries_have_index(entries) -> bool:
    return all(isinstance(e, dict) and isinstance(e.get("index"), int) for e in entries)

Type guard

def is_indexed_delta_entry(entry) -> bool:
    return is_dict(entry) and isinstance(entry.get("index"), int)

Try / catch

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

Prevention

When it happens

Trigger: Streaming payloads where list delta dicts omit index - schema drift between the API emitting the delta and the SDK version parsing it, or hand-built delta fixtures in tests that forget the index key.

Common situations: API schema evolution outpacing an older pinned SDK; beta endpoints mid-rollout; test fixtures authored from stale docs.

Related errors

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