cocoindex-io/cocoindex · error · ValueError

Column {name!r} cannot combine ZvecFtsType with ZvecType.

Error message

Column {name!r} cannot combine ZvecFtsType with ZvecType.

What it means

Annotation-conflict guard in _resolve_column. ZvecFtsType marks a column as a full-text search field and ZvecType as a typed scalar column; a single zvec column cannot be both, so the two annotations on one field would produce contradictory schema definitions. Raised during collection schema building (from_class) when both annotations are present on the same column. Keep only one of the two annotations per column.

Source

Thrown at python/cocoindex/connectors/zvec/_target.py:401

    if vector_def is not None and vector_def.sparse:
        return _Column(
            name=name,
            kind="sparse",
            data_type=_zvec.DataType.SPARSE_VECTOR_FP32,
            nullable=type_info.nullable,
            metric=vector_def.metric,
        )

    if type_info.base_type is np.ndarray:
        raise ValueError(
            f"Vector column {name!r} requires a VectorSchema (provide it via an "
            "Annotated NDArray or column_overrides)."
        )

    # Full-text field: str marked with ZvecFtsType.
    if fts_type is not None:
        if zvec_type is not None:
            raise ValueError(
                f"Column {name!r} cannot combine ZvecFtsType with ZvecType."
            )
        if type_info.base_type is not str:
            raise ValueError(
                f"ZvecFtsType on column {name!r} requires a str field, got "
                f"{type_info.base_type!r}."
            )
        return _Column(
            name=name,
            kind="fts",
            data_type=_zvec.DataType.STRING,
            nullable=type_info.nullable,
            tokenizer_name=fts_type.tokenizer_name,
            filters=fts_type.filters,
            extra_params=fts_type.extra_params,
        )

    # Scalar field.

View on GitHub (pinned to e84aa99b32)

Solutions

1. Remove the ZvecType annotation and keep only ZvecFtsType for FTS fields
2. Or remove ZvecFtsType if the column should be a regular typed column
3. Split into two columns if both behaviors are needed

Example fix

// before
text: Annotated[str, ZvecFtsType(), ZvecType()]
// after
text: Annotated[str, ZvecFtsType()]

annots = [a for a in get_args(hint)[1:]]
assert not (any(isinstance(a, ZvecFtsType) for a in annots) and any(isinstance(a, ZvecType) for a in annots)), "remove ZvecType from FTS fields"

try:
    schema = ZvecCollection.from_class(Row)
except ValueError as e:
    if "cannot combine ZvecFtsType with ZvecType" in str(e):
        # drop one of the two annotations on that column
        ...
    else:
        raise

When it happens

Trigger: Annotating a str field with both ZvecFtsType and ZvecType (e.g. Annotated[str, ZvecFtsType(), ZvecType(...)]) in a from_class row type.

Common situations: Copy-pasting annotations between fields; incrementally converting a field to FTS without removing the old ZvecType annotation.

Related errors

• Invalid {kind}: {name!r}
• Invalid collection name {name!r}: zvec requires at least {_M
• Invalid vector dimension for {name!r}: {vector_schema.size}
• Vector column {name!r} requires a VectorSchema (provide it v
• ZvecFtsType on column {name!r} requires a str field, got {ty

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/18e5ecc035c16e39. Report an issue: GitHub.