cocoindex-io/cocoindex · error

Invalid vector dimension: {dimension}

Error message

Invalid vector dimension: {dimension}

What it means

build_vector_index_create() validates that the vector index dimension is a positive integer and raises for dimension <= 0. FalkorDB's VECTOR index requires a positive dimension option; a non-positive value would produce an invalid or meaningless index, so the library rejects it up front.

Source

Thrown at python/cocoindex/connectors/falkordb/_cypher.py:187

        raise ValueError("build_relationship_index_drop requires at least one field")
    field_list = ", ".join(f"e.{_quote(f)}" for f in fields)
    return f"DROP INDEX FOR ()-[e:{_quote(rel_type)}]-() ON ({field_list})"


def build_vector_index_create(
    label: str,
    field: str,
    dimension: int,
    metric: str,
) -> str:
    """``CREATE VECTOR INDEX FOR (e:`Label`) ON (e.`field`) OPTIONS {...}``.

    ``metric`` is the FalkorDB-side ``similarityFunction`` value
    (e.g. ``"cosine"``, ``"euclidean"``). Caller is responsible for translating
    user-facing names into the FalkorDB vocabulary before invoking.
    """
    if dimension <= 0:
        raise ValueError(f"Invalid vector dimension: {dimension}")
    return (
        f"CREATE VECTOR INDEX FOR (e:{_quote(label)}) ON (e.{_quote(field)}) "
        f"OPTIONS {{dimension: {int(dimension)}, similarityFunction: '{metric}'}}"
    )


def build_vector_index_drop(label: str, field: str) -> str:
    """``DROP VECTOR INDEX FOR (e:`Label`) ON (e.`field`)``.

    Confirmed via spike against FalkorDB latest: the DROP statement does NOT
    take an index name — it identifies the index by (label, field).
    """
    return f"DROP VECTOR INDEX FOR (e:{_quote(label)}) ON (e.{_quote(field)})"

View on GitHub (pinned to e84aa99b32)

Solutions

1. Set dimension to the embedding model's output size (e.g. 384 for all-MiniLM-L6-v2, 1536 for OpenAI text-embedding-3-small).
2. Ensure the embedding model is initialized before declaring the vector index so its dimension is available.
3. Add a caller-side check that dimension is a positive int before invoking the builder.

Example fix

// before
dimension = 0  # not yet known
build_vector_index_create(label="Doc", field="embedding", dimension=dimension, metric="cosine")
// after
dimension = model.get_sentence_embedding_dimension()  # e.g. 384
build_vector_index_create(label="Doc", field="embedding", dimension=dimension, metric="cosine")

if not isinstance(dimension, int) or dimension <= 0:
    raise ValueError(f'embedding dimension must be a positive int, got {dimension!r}')
cypher = build_vector_index_create(label=label, field=field, dimension=dimension, metric=metric)

def valid_dimension(d: object) -> bool:
    return isinstance(d, int) and not isinstance(d, bool) and d > 0

try:
    cypher = build_vector_index_create(label, field, dimension, metric)
except ValueError as e:
    logger.error('vector index misconfigured: %s', e)
    raise ConfigError('initialize the embedding model to resolve its dimension before declaring a vector index') from e

When it happens

Trigger: Calling build_vector_index_create with dimension=0, a negative number, or a dimension resolved from an uninitialized variable — e.g. embedding model metadata that hasn't been loaded yet.

Common situations: Embedding dimension not yet known when the index is declared (model loaded lazily, dimension defaults to 0); misconfigured vector field spec; copying a template and leaving dimension unset.

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

• Invalid FalkorDB {kind}: {name!r}. Must match [a-zA-Z_][a-zA
• Invalid vector dimension: {dimension}
• build_node_upsert requires at least one primary key field
• build_node_delete requires at least one primary key field
• build_relationship_upsert requires PK fields for from, to, a

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