chroma-core/chroma · error · ValueError

Non-empty lists are required for {zero_lengths}

Error message

Non-empty lists are required for {zero_lengths}

What it means

The same record-set validation that requires at least one field also rejects provided-but-empty lists: any non-None field with length 0 — e.g. ids=[] alongside metadatas=[{'a': 1}] — raises ValueError('Non-empty lists are required for {zero_lengths}') naming each offending field. It is the companion guard to the all-None and unequal-length checks.

Source

Thrown at chromadb/api/types.py:465

        validate_metadatas(record_set["metadatas"])


def _validate_record_set_length_consistency(record_set: BaseRecordSet) -> None:
    lengths = [len(lst) for lst in record_set.values() if lst is not None]  # type: ignore[arg-type]

    if not lengths:
        raise ValueError(
            f"At least one of one of {', '.join(record_set.keys())} must be provided"
        )

    zero_lengths = [
        key
        for key, lst in record_set.items()
        if lst is not None and len(lst) == 0  # type: ignore[arg-type]
    ]

    if zero_lengths:
        raise ValueError(f"Non-empty lists are required for {zero_lengths}")

    if len(set(lengths)) > 1:
        error_str = ", ".join(
            f"{key}: {len(lst)}"
            for key, lst in record_set.items()
            if lst is not None  # type: ignore[arg-type]
        )
        raise ValueError(f"Unequal lengths for fields: {error_str}")


def validate_record_set_for_embedding(
    record_set: BaseRecordSet, embeddable_fields: Optional[Set[str]] = None
) -> None:
    """
    Validates that the Record is ready to be embedded, i.e. that it contains exactly one of the embeddable fields.
    """
    if record_set["embeddings"] is not None:
        raise ValueError("Attempting to embed a record that already has embeddings.")

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Skip empty batches entirely: bail out if any provided list has length 0
2. Use None (or omit the kwarg) for fields you don't have — never []
3. Ensure producers emit all field lists with the same non-zero length

Example fix

// before
coll.add(ids=[], metadatas=[{'a': 1}])  # ValueError: non-empty lists required

// after
if ids and metadatas:
    coll.add(ids=ids, metadatas=metadatas)

def validate_batch(record: dict) -> dict:
    provided = {k: v for k, v in record.items() if v is not None}
    if not provided:
        raise ValueError('at least one field must be provided')
    empty = [k for k, v in provided.items() if len(v) == 0]
    if empty:
        raise ValueError(f'non-empty lists required for {empty}')
    lengths = {k: len(v) for k, v in provided.items()}
    if len(set(lengths.values())) > 1:
        raise ValueError(f'unequal lengths: {lengths}')
    return provided

coll.add(**validate_batch(batch))

When it happens

Trigger: coll.add(ids=[], metadatas=[{'a': 1}]), coll.upsert(documents=[]), or any add/update/upsert where at least one supplied list is empty (usually alongside other non-empty fields).

Common situations: Empty trailing batches where one field list is empty but others still hold values; dict construction defaulting a missing field to [] instead of None; zip-based field building that truncates to zero unevenly.

Related errors

• At least one of one of {', '.join(record_set.keys())} must b
• Expected Embeddings to be non-empty list or numpy array, got
• embeddings and documents cannot both be undefined
• Expected ids to be strings, found ${typeof ids[i]} at index
• ids, embeddings, metadatas, and documents must all be the sa

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/d751ff7ed42902d5. Report an issue: GitHub.