tirth8205/code-review-graph · error · RuntimeError

OpenAI API returned malformed indices (got {indices}, expect

Error message

OpenAI API returned malformed indices (got {indices}, expected permutation of 0..{len(texts) - 1}) — refusing to misalign vectors.

What it means

The provider validates that when every returned embedding item carries an integer `index`, those indices must form an exact permutation of 0..N-1 matching the input texts. If indices are duplicated, out of range, or incomplete, it raises this RuntimeError rather than risk pairing vectors with the wrong texts — embeddings are positional, so misalignment would silently corrupt semantic search.

Source

Thrown at code_review_graph/embeddings.py:540

                # compatible gateways re-order results or drop entries on
                # partial failure, and others omit `index` entirely. Three
                # disjoint cases:
                #   1. All items have a valid int ``index``: must form a
                #      permutation of 0..N-1, then sort and use.
                #   2. NO item carries an ``index`` field: trust server
                #      order, only verify count matches.
                #   3. Anything in between (partial indices, str indices,
                #      missing on some): refuse. Zipping server order in
                #      that case would happily misalign the indexed items.
                any_has_index = any("index" in item for item in data)
                all_int_index = all(
                    isinstance(item.get("index"), int) for item in data
                )
                if all_int_index:
                    expected = set(range(len(texts)))
                    indices = [int(item["index"]) for item in data]
                    if len(set(indices)) != len(indices) or set(indices) != expected:
                        raise RuntimeError(
                            "OpenAI API returned malformed indices "
                            f"(got {indices}, expected permutation of "
                            f"0..{len(texts) - 1}) — refusing to misalign vectors."
                        )
                    data = sorted(data, key=lambda item: int(item["index"]))
                elif not any_has_index:
                    if len(data) != len(texts):
                        raise RuntimeError(
                            f"OpenAI API returned {len(data)} embeddings for "
                            f"{len(texts)} inputs with no index field — "
                            "refusing to misalign vectors."
                        )
                else:
                    # Mixed: some items have index, others don't (or carry
                    # non-int index). Server order would silently misplace
                    # the indexed items, so we refuse.
                    raise RuntimeError(
                        "OpenAI API returned mixed indexed/unindexed data — "

View on GitHub (pinned to b58668751a)

Solutions

Check gateway/proxy logs: it likely dropped or mislabeled items in the batch
Reduce batch size to see if the gateway handles smaller batches correctly
Fix or patch the gateway so data[i].index covers exactly 0..N-1
Report/upgrade the gateway — its embeddings response violates the OpenAI spec

Defensive patterns

Strategy: try-catch

Validate before calling

# Split large batches: gateways are more likely to drop/misindex big batches
batches = [texts[i:i+64] for i in range(0, len(texts), 64)]
vecs = [provider.embed(b) for b in batches]

Try / catch

try:
    vecs = provider.embed(batch)
except RuntimeError as e:
    if "malformed indices" in str(e):
        # halve batch and retry to dodge gateway index bugs
        mid = max(1, len(batch)//2)
        vecs = provider.embed(batch[:mid]) + provider.embed(batch[mid:])
    else:
        raise

Prevention

Use moderate batch sizes (32–128) against third-party OpenAI-compatible gateways
Run a canary batch through a new gateway and assert len(result) == len(inputs)
Treat any 'refusing to misalign' error as a server bug — report it, don't work around silently

When it happens

Trigger: embed() against a gateway that returns all items indexed but with duplicated indices, missing indices, or values outside 0..len(texts)-1 (e.g. index starting at 1, or dropped items).

Common situations: Custom OpenAI-compatible servers with off-by-one index bugs, batch truncation under load, or gateways that re-index after dropping failed items.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of tirth8205/code-review-graph@b58668751a (2026-08-28). Data as JSON: /api/errors/e34cea8f09cc385f. Report an issue: GitHub.