{"record":{"id":"49a235a544e6b28d","repo":"cocoindex-io/cocoindex","slug":"vectordef-schema-must-implement-vectorschemaprovid","errorCode":null,"errorMessage":"VectorDef schema must implement VectorSchemaProvider: {vector_def.schema}","messagePattern":"VectorDef schema must implement VectorSchemaProvider: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/valkey/_target.py","lineNumber":110,"sourceCode":"    \"\"\"\n\n    name: str\n    type: Literal[\"text\", \"tag\", \"numeric\"]\n    sortable: bool = False\n\n\nclass _ResolvedVectorDef(msgspec.Struct, frozen=True, tag=True):\n    \"\"\"Internal resolved form after calling __coco_vector_schema__().\"\"\"\n\n    schema: res_schema.VectorSchema\n    distance: Literal[\"cosine\", \"l2\", \"ip\"]\n    algorithm: Literal[\"hnsw\", \"flat\"]\n\n\nasync def _resolve_vector_def(vector_def: VectorDef) -> _ResolvedVectorDef:\n    vs = await res_schema.get_vector_schema(vector_def.schema)\n    if vs is None:\n        raise ValueError(\n            f\"VectorDef schema must implement VectorSchemaProvider: {vector_def.schema}\"\n        )\n    return _ResolvedVectorDef(\n        schema=vs,\n        distance=vector_def.distance,\n        algorithm=vector_def.algorithm,\n    )\n\n\n@dataclass(slots=True)\nclass IndexSchema:\n    \"\"\"Schema definition for a Valkey search index.\n\n    Defines the vector field and optional indexed payload fields. Use the async\n    ``create`` classmethod to resolve vector dimensions from a provider.\n\n    Example:\n        ```python","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/valkey/_target.py#L92-L128","documentation":"A VectorDef passed to the Valkey connector references a `schema` object, and `_resolve_vector_def` resolves it via `res_schema.get_vector_schema`. When that returns None — meaning the provided object does not implement the VectorSchemaProvider protocol (it cannot describe its dtype/size) — this ValueError is raised, since the connector cannot build the Valkey index field without dtype and dimension info.","triggerScenarios":"Calling `create` with VectorDef(schema=<something that is not a VectorSchemaProvider>, ...) — e.g. passing a raw numpy array, a plain list, a string, or a custom embedding wrapper that lacks the provider interface.","commonSituations":"Passing a model or function instead of a schema object; hand-rolling a vector source class without implementing VectorSchemaProvider; wiring the wrong object (the embedding output rather than its declared schema) into VectorDef.schema.","solutions":["Pass a schema object implementing VectorSchemaProvider (one that res_schema.get_vector_schema can resolve to a VectorSchema with dtype and size).","If you have a custom vector source, implement the VectorSchemaProvider protocol on it (expose dtype and vector size).","Check that you're not accidentally passing the embedding values themselves; wrap them in the proper schema declaration for the connector."],"exampleFix":"// before\nVectorDef(schema=embeddings_array, distance=\"cosine\")\n\n// after\nVectorDef(schema=MyVectorSchema(dtype=np.float32, size=768), distance=\"cosine\")","handlingStrategy":"type-guard","validationCode":"from cocoindex.resources import schema as res_schema\nif await res_schema.get_vector_schema(vdef.schema) is None:\n    raise TypeError(f\"{vdef.schema!r} does not implement VectorSchemaProvider\")","typeGuard":"def is_vector_schema_provider(obj: object) -> bool:\n    return hasattr(obj, \"dtype\") and hasattr(obj, \"size\")","tryCatchPattern":"try:\n    target = await valkey.create(...)\nexcept ValueError as e:\n    if \"VectorSchemaProvider\" in str(e):\n        raise ConfigError(\"Pass a VectorSchemaProvider object to VectorDef.schema\") from e\n    raise","preventionTips":["Use the library's declared schema types for VectorDef.schema, not raw arrays or models","Implement VectorSchemaProvider on any custom vector source class","Validate VectorDef construction with a quick get_vector_schema call in tests"],"tags":["python","protocol","vector","valkey"],"backgroundTag":"invalid-argument-value","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"}