What causes "Invalid vector dimension: {vector_schema.size}" in cocoindex-io/cocoindex?

Set VectorSchemaProvider(size=N) to the actual embedding dimension (e.g. 384, 768).

cocoindex-io/cocoindex · error · ValueError

Invalid vector dimension

Error message

Invalid vector dimension: {vector_schema.size}

What it means

A VectorSchemaProvider attached to an np.ndarray field reports a non-positive vector size. SurrealDB's array<float, N> requires N to be a positive dimension, so CocoIndex rejects the mapping when size <= 0.

Solutions

Set VectorSchemaProvider(size=N) to the actual embedding dimension (e.g. 384, 768).
Derive N from the embedding model's output dimension constant instead of runtime sample data.
Add a startup assertion that the configured size matches model output.

Example fix

// before
VectorSchemaProvider(size=0)
// after
VectorSchemaProvider(size=768)

Defensive patterns

Strategy: validation

Validate before calling

if vector_schema.size <= 0:
    raise ValueError(f"vector size must be positive, got {vector_schema.size}")

Type guard

def has_valid_vector_dimension(vs) -> bool:
    return vs is not None and vs.size > 0

Try / catch

try:
    target = table_target(record_type, ...)
except ValueError as e:
    if "Invalid vector dimension" in str(e):
        # set size to the embedding model's output dimension
        ...

Prevention

Use the embedding model's documented output dimension as a constant, not derived runtime data.
Never default vector size to 0; require explicit configuration.
Assert dimension matches model output once at startup.

When it happens

Trigger: Passing VectorSchemaProvider with size=0 or a negative size (e.g. an uninitialized/0-length dimension variable, or reading the size from an empty array's shape) while declaring a SurrealDB vector column.

Common situations: Computing the dimension from an empty sample array; a config default of 0 that was never set; typo like size=-1 as a placeholder.

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/f6f96de4a2d3fc03. Report an issue: GitHub.

Appendix: source

Thrown at python/cocoindex/connectors/surrealdb/_target.py:286

    type_info = analyze_type_info(python_type)

    # Check for SurrealType annotation override
    for annotation in type_info.annotations:
        if isinstance(annotation, SurrealType):
            return _TypeMapping(annotation.surreal_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: map to array<float, N>
    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}")

        return _TypeMapping(
            surreal_type=f"array<float, {vector_schema.size}>",
            encoder=_ndarray_encoder,
        )

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

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

View on GitHub (pinned to e84aa99b32)