cocoindex-io/cocoindex · error

Invalid vector dimension: {vector_schema.size}

Error message

Invalid vector dimension: {vector_schema.size}

What it means

After confirming a `VectorSchemaProvider` exists for an ndarray column, `_get_type_mapping` validates that its dimension is positive. A dimension of 0 or negative cannot produce a valid FalkorDB vector type (`vector<float32, N>`), so the library raises ValueError.

Source

Thrown at python/cocoindex/connectors/falkordb/_target.py:276

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, FalkorType):
            return _TypeMapping(annotation.falkor_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(
            falkor_type=f"vector<float32, {vector_schema.size}>",
            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. Set the provider dimension to a positive integer matching the embedding model output, e.g. `VectorSchemaProvider(dimension=768)`.
  2. If the dimension is computed, assert it before constructing the schema: `assert dim > 0`.
  3. Log/inspect the value passed as `dimension` — trace where 0/negative came from.

Example fix

// before
res_schema.VectorSchemaProvider(dimension=len(embedding))  # embedding may be empty
// after
dim = len(embedding) or 384
assert dim > 0
res_schema.VectorSchemaProvider(dimension=dim)
Defensive patterns

Strategy: validation

Validate before calling

dim = EMBEDDING_DIM  # from config/model
if not isinstance(dim, int) or dim <= 0:
    raise ValueError(f"Embedding dimension must be a positive int, got {dim!r}")
provider = res_schema.VectorSchemaProvider(dimension=dim)

Try / catch

try:
    schema = await falkordb.TableSchema.from_class(Row, column_overrides=overrides)
except ValueError as e:
    if "Invalid vector dimension" in str(e):
        logging.error("Check the dimension passed to VectorSchemaProvider: %s", e)
    raise

Prevention

When it happens

Trigger: Passing `VectorSchemaProvider(dimension=0)` or a negative dimension (e.g. a dimension computed from an empty list length or an unset config variable) in `column_overrides` for an `np.ndarray` field, then building the schema via `from_class`.

Common situations: Reading the dimension from a config/env var that resolves to 0; computing `len(model_dims.get(name, []))` on a missing entry; typo like `dimension=-1` as a placeholder never replaced.

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