cocoindex-io/cocoindex · error · ValueError

Column 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.

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.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Invalid collection name
• Invalid
• Invalid vector dimension for
• Primary key column not found in columns
• Vector column requires a VectorSchema (provide it via an…

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

Appendix: 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)