chroma-core/chroma · error · ValueError

Attempting to embed a record that already has embeddings.

Error message

Attempting to embed a record that already has embeddings.

What it means

validate_record_set_for_embedding (chromadb/api/types.py:476) is run on record sets that are about to be embedded. Its first invariant is that the record set does not already carry embeddings - Chroma cannot mix 'embed this for me' with 'use my vectors'. In the current code base every public entry point (add/upsert/update/query in chromadb/api/models/CollectionCommon.py) only invokes this validator when embeddings is None, so hitting this message in practice means the validator was called directly on a pre-embedded record set, typically from custom code reusing the chromadb.api.types helpers.

Source

Thrown at chromadb/api/types.py:483

        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.")
    if embeddable_fields is None:
        embeddable_fields = get_default_embeddable_record_set_fields()
    validate_record_set_contains_one(record_set, embeddable_fields)


def validate_record_set_contains_any(
    record_set: BaseRecordSet, contains_any: Set[str]
) -> None:
    """
    Validates that at least one of the fields in contains_any is not None.
    """
    _validate_record_set_contains(record_set, contains_any)

    if not any(record_set[field] is not None for field in contains_any):  # type: ignore[literal-required]
        raise ValueError(f"At least one of {', '.join(contains_any)} must be provided")


def validate_record_set_contains_one(

View on GitHub (pinned to aecdd12c8a)

Solutions

If you already have vectors, pass embeddings= to add/upsert/query - no embedding step runs and the validator is never reached
In custom code mirroring CollectionCommon, guard the call: if record_set['embeddings'] is None: validate_record_set_for_embedding(...)
Leave the 'embeddings' key None until after the embedding step, and populate it only afterwards

Example fix

# before (custom pipeline)
validate_record_set_for_embedding(record_set=rs)  # rs['embeddings'] already set

# after
if rs['embeddings'] is None:
    validate_record_set_for_embedding(record_set=rs)
    rs['embeddings'] = embed(rs)

Defensive patterns

Strategy: validation

Validate before calling

if query_embeddings is not None:
    results = collection.query(query_embeddings=query_embeddings, n_results=k)
else:
    results = collection.query(query_texts=texts, n_results=k)

Type guard

def needs_client_embedding(record_set) -> bool:
    return record_set.get('embeddings') is None

Try / catch

try:
    validate_record_set_for_embedding(record_set=rs)
except ValueError as e:
    if 'already has embeddings' in str(e):
        # skip embedding, use the existing vectors
        pass
    raise

Prevention

Never pass embeddings together with content meant to be embedded
Keep EF-backed and vector-backed search in separate code paths
In custom pipelines, guard validator calls with 'if rs['embeddings'] is None'

When it happens

Trigger: Calling chromadb.api.types.validate_record_set_for_embedding on a record set whose 'embeddings' key is already populated; passing a pre-embedded record set into a custom ingestion pipeline that re-validates it for embedding. Through the public API the equivalent user mistake (supplying both embeddings and documents to the same call) is caught by other checks or resolved by using the supplied embeddings.

Common situations: Teams wrapping Chroma's internal validation helpers in their own ingestion frameworks; upgrades across Chroma versions where these invariants moved between modules; copy-pasting internal example code that builds record sets manually.

Related errors

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