cocoindex-io/cocoindex · error · ValueError

Invalid vector dimension: {vector_schema.size}

Error message

Invalid vector dimension: {vector_schema.size}

What it means

This ValueError is raised by _get_type_mapping when a VectorSchemaProvider is supplied for an np.ndarray column but its size is zero or negative. Neo4j LIST<FLOAT> mapping requires a positive vector dimension. It complements the missing-provider check on the preceding line.

Source

Thrown at python/cocoindex/connectors/neo4j/_target.py:315

async def _get_type_mapping(
    python_type: Any, *, vector_schema: res_schema.VectorSchema | None = None
) -> _TypeMapping:
    type_info = analyze_type_info(python_type)

    for annotation in type_info.annotations:
        if isinstance(annotation, Neo4jType):
            return _TypeMapping(annotation.neo4j_type, annotation.encoder)

    base_type = type_info.base_type

    if base_type in _LEAF_TYPE_MAPPINGS:
        return _LEAF_TYPE_MAPPINGS[base_type]

    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(
            neo4j_type="LIST<FLOAT>",
            encoder=_ndarray_to_list,
        )
    elif vector_schema is not None:
        raise ValueError(
            "VectorSchemaProvider is only supported for NumPy ndarray type. "
            f"Got type: {python_type}"
        )

    if isinstance(type_info.variant, (SequenceType,)):
        return _ARRAY_MAPPING
    if isinstance(type_info.variant, (MappingType, RecordType, UnionType, AnyType)):
        return _OBJECT_MAPPING

    return _OBJECT_MAPPING

View on GitHub (pinned to e84aa99b32)

Solutions

  1. Construct the provider with the real embedding dimension, e.g. VectorSchemaProvider(size=384).
  2. Validate size > 0 where the dimension is loaded from config.
  3. Ensure the embedding model is initialized so its dimension is known before schema construction.

Example fix

// before
VectorSchemaProvider(size=0)
// after
VectorSchemaProvider(size=1536)
Defensive patterns

Strategy: validation

Validate before calling

if vector_schema is not None and vector_schema.size <= 0:
    raise ValueError("VectorSchemaProvider size must be > 0 (set the embedding dimension)")

Try / catch

try:
    schema = await TableSchema.from_class(Record, column_overrides=overrides)
except ValueError as e:
    raise RuntimeError("vector dimension misconfigured; check EMBED_DIM") from e

Prevention

When it happens

Trigger: Constructing VectorSchemaProvider(size=0) or a negative size — e.g. dimension read from an uninitialized embedding model config, a defaulted 0, or computed dimension that evaluated to 0.

Common situations: Embedding dimension not yet known at schema-build time (placeholder 0); config file with a missing/zero 'dimensions' value; programmatically deriving size from an empty shape.

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