{"record":{"id":"f49e17da573f3c2e","repo":"cocoindex-io/cocoindex","slug":"vector-column-name-r-requires-a-vectorschema-pr","errorCode":null,"errorMessage":"Vector column {name!r} requires a VectorSchema (provide it via an Annotated NDArray or column_overrides).","messagePattern":"Vector column (.+?) requires a VectorSchema \\(provide it via an Annotated NDArray or column_overrides\\)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/zvec/_target.py","lineNumber":393,"sourceCode":"            data_type=_dense_vector_data_type(vector_schema.dtype),\n            nullable=type_info.nullable,\n            dimension=vector_schema.size,\n            metric=vd.metric,\n            quantize=vd.quantize,\n        )\n\n    # Sparse vector: explicitly marked via ZvecVectorDef(sparse=True).\n    if vector_def is not None and vector_def.sparse:\n        return _Column(\n            name=name,\n            kind=\"sparse\",\n            data_type=_zvec.DataType.SPARSE_VECTOR_FP32,\n            nullable=type_info.nullable,\n            metric=vector_def.metric,\n        )\n\n    if type_info.base_type is np.ndarray:\n        raise ValueError(\n            f\"Vector column {name!r} requires a VectorSchema (provide it via an \"\n            \"Annotated NDArray or column_overrides).\"\n        )\n\n    # Full-text field: str marked with ZvecFtsType.\n    if fts_type is not None:\n        if zvec_type is not None:\n            raise ValueError(\n                f\"Column {name!r} cannot combine ZvecFtsType with ZvecType.\"\n            )\n        if type_info.base_type is not str:\n            raise ValueError(\n                f\"ZvecFtsType on column {name!r} requires a str field, got \"\n                f\"{type_info.base_type!r}.\"\n            )\n        return _Column(\n            name=name,\n            kind=\"fts\",","sourceCodeStart":375,"sourceCodeEnd":411,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/zvec/_target.py#L375-L411","documentation":"An ndarray-typed column without an associated VectorSchema annotation cannot be mapped to a zvec dense vector column. _resolve_column raises ValueError telling you to supply VectorSchema via an Annotated NDArray or column_overrides.","triggerScenarios":"Declaring a column as plain np.ndarray (or ndarray via column_overrides) without VectorSchema metadata when calling from_class.","commonSituations":"Forgetting the Annotated wrapper; passing a bare ndarray type in column_overrides without a vector schema; converting an existing schema where vector metadata was dropped.","solutions":["Annotate the column: Annotated[np.ndarray, VectorSchema(size=D)]","Or supply the VectorSchema through column_overrides for that column","Add the missing VectorSchema via column_overrides for that column"],"exampleFix":"// before\nvec: np.ndarray\n// after\nvec: Annotated[np.ndarray, VectorSchema(size=384, vector_def=ZvecVectorDef())]","handlingStrategy":"validation","validationCode":"from typing import Annotated, get_type_hints\nhints = get_type_hints(Row, include_extras=True)\nfor n, t in hints.items():\n    if get_origin(t) is np.ndarray:\n        assert any(isinstance(a, VectorSchema) for a in get_args(t)[1:]), f\"{n} missing VectorSchema\"","typeGuard":"def has_vector_schema(annotation: object) -> bool:\n    return get_origin(annotation) is Annotated and any(\n        isinstance(m, VectorSchema) for m in get_args(annotation)[1:])","tryCatchPattern":"try:\n    schema = ZvecCollection.from_class(Row)\nexcept ValueError as e:\n    if \"requires a VectorSchema\" in str(e):\n        # fix the annotation or pass column_overrides={...}\n        ...\n    else:\n        raise","preventionTips":["Always wrap ndarray columns in Annotated[..., VectorSchema(size=D)]","Prefer class annotations over bare column_overrides for vector columns","Lint row classes for missing VectorSchema before runtime"],"tags":["python","validation","vector","zvec"],"backgroundTag":"missing-required-argument","analyzedSha":"e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b","analyzedAt":"2026-09-08T15:59:19.997Z","contentChangedAt":"2026-09-08T15:59:19.997Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}