cocoindex-io/cocoindex · error · ValueError

Invalid vector dimension: {vector_schema.size}

Error message

Invalid vector dimension: {vector_schema.size}

What it means

When an ndarray field has a VectorSchemaProvider, its `size` defines the sqlite-vec column type `float[N]`. A size of zero or negative cannot yield a valid vector type, so `_get_type_mapping` raises this ValueError. It guards against misconfigured or uninitialized vector schemas.

Source

Thrown at python/cocoindex/connectors/sqlite/_target.py:261

    # Check for SqliteType annotation override
    for annotation in type_info.annotations:
        if isinstance(annotation, SqliteType):
            return _TypeMapping(annotation.sqlite_type, annotation.encoder)

    base_type = type_info.base_type

    # Check direct leaf type mappings
    if base_type in _LEAF_TYPE_MAPPINGS:
        return _LEAF_TYPE_MAPPINGS[base_type]

    # NumPy ndarray: serialize to sqlite-vec compatible format
    if base_type is np.ndarray:
        if vector_schema is None:
            raise ValueError("VectorSchemaProvider is required for NumPy ndarray type.")

        if vector_schema.size <= 0:
            raise ValueError(f"Invalid vector dimension: {vector_schema.size}")

        # sqlite-vec uses float[N] type (e.g., float[384])
        import sqlite_vec  # type: ignore

        return _TypeMapping(
            f"float[{vector_schema.size}]", sqlite_vec.serialize_float32
        )

    elif vector_schema is not None:
        raise ValueError(
            f"VectorSchemaProvider is only supported for NumPy ndarray type. Got type: {python_type}"
        )

    # Complex types that need JSON encoding
    if isinstance(
        type_info.variant, (SequenceType, MappingType, RecordType, UnionType, AnyType)
    ):
        return _JSON_MAPPING

View on GitHub (pinned to e84aa99b32)

Solutions

  1. Set the provider's size to the actual positive embedding dimension (e.g. 384, 768).
  2. Read the dimension from the embedding model at startup and assert it's > 0 before building the target.
  3. Fix the constant/config supplying the size if it defaults to 0.

Example fix

// before
embedding: Annotated[np.ndarray, VectorSchemaProvider(size=0)]
// after
embedding: Annotated[np.ndarray, VectorSchemaProvider(size=384)]
Defensive patterns

Strategy: validation

Validate before calling

dim = embedding_model.get_sentence_embedding_dimension()
assert dim and dim > 0, f"Bad embedding dimension: {dim}"

Try / catch

try:
    target = sqlite.table_target(record_type=Row, ...)
except ValueError as e:
    if "Invalid vector dimension" in str(e):
        raise ConfigError("VectorSchemaProvider size must be a positive integer") from e
    raise

Prevention

When it happens

Trigger: Declaring a field with `VectorSchemaProvider(size=0)` (or a negative size), or constructing the provider dynamically from an empty/failed dimension lookup.

Common situations: Computing the dimension from an empty model config, copy-pasting a placeholder size=0, or reading the dimension from an uninitialized embedding model.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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