cocoindex-io/cocoindex · error · ValueError

VectorDef schema must implement VectorSchemaProvider: {vecto

Error message

VectorDef schema must implement VectorSchemaProvider: {vector_def.schema}

What it means

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.

Source

Thrown at python/cocoindex/connectors/valkey/_target.py:110

    """

    name: str
    type: Literal["text", "tag", "numeric"]
    sortable: bool = False


class _ResolvedVectorDef(msgspec.Struct, frozen=True, tag=True):
    """Internal resolved form after calling __coco_vector_schema__()."""

    schema: res_schema.VectorSchema
    distance: Literal["cosine", "l2", "ip"]
    algorithm: Literal["hnsw", "flat"]


async def _resolve_vector_def(vector_def: VectorDef) -> _ResolvedVectorDef:
    vs = await res_schema.get_vector_schema(vector_def.schema)
    if vs is None:
        raise ValueError(
            f"VectorDef schema must implement VectorSchemaProvider: {vector_def.schema}"
        )
    return _ResolvedVectorDef(
        schema=vs,
        distance=vector_def.distance,
        algorithm=vector_def.algorithm,
    )


@dataclass(slots=True)
class IndexSchema:
    """Schema definition for a Valkey search index.

    Defines the vector field and optional indexed payload fields. Use the async
    ``create`` classmethod to resolve vector dimensions from a provider.

    Example:
        ```python

View on GitHub (pinned to e84aa99b32)

Solutions

1. Pass a schema object implementing VectorSchemaProvider (one that res_schema.get_vector_schema can resolve to a VectorSchema with dtype and size).
2. If you have a custom vector source, implement the VectorSchemaProvider protocol on it (expose dtype and vector size).
3. Check that you're not accidentally passing the embedding values themselves; wrap them in the proper schema declaration for the connector.

Example fix

// before
VectorDef(schema=embeddings_array, distance="cosine")

// after
VectorDef(schema=MyVectorSchema(dtype=np.float32, size=768), distance="cosine")

from cocoindex.resources import schema as res_schema
if await res_schema.get_vector_schema(vdef.schema) is None:
    raise TypeError(f"{vdef.schema!r} does not implement VectorSchemaProvider")

def is_vector_schema_provider(obj: object) -> bool:
    return hasattr(obj, "dtype") and hasattr(obj, "size")

try:
    target = await valkey.create(...)
except ValueError as e:
    if "VectorSchemaProvider" in str(e):
        raise ConfigError("Pass a VectorSchemaProvider object to VectorDef.schema") from e
    raise

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• VectorSchemaProvider is required for NumPy ndarray type.
• Invalid vector dimension: {vector_schema.size}
• VectorSchemaProvider is only supported for NumPy ndarray typ
• VectorSchemaProvider is required for NumPy ndarray type.
• Invalid vector dimension: {vector_schema.size}

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