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

Pass the actual embedding dimension, e.g. 384 or 1536.

cocoindex-io/cocoindex · error · ValueError

Invalid vector dimension: {dimension}

Error message

Invalid vector dimension: {dimension}

What it means

This ValueError is raised by build_vector_index_create when the vector dimension is zero or negative. Neo4j vector indexes require vector.dimensions to be a positive integer in the indexConfig options. The library rejects invalid dimensions before emitting the CREATE VECTOR INDEX statement.

Source

Thrown at python/cocoindex/connectors/neo4j/_cypher.py:255

    """``DROP CONSTRAINT <name> IF EXISTS``."""
    return f"DROP CONSTRAINT {_quote(name)} IF EXISTS"


def build_vector_index_create(
    name: str,
    label: str,
    field: str,
    dimension: int,
    metric: str,
) -> str:
    """``CREATE VECTOR INDEX <name> IF NOT EXISTS FOR (n:`Label`) ON n.`field` OPTIONS {...}``.

    ``metric`` is the Neo4j ``vector.similarity_function`` value
    (``"cosine"`` or ``"euclidean"``). Caller is responsible for translating
    user-facing names into the Neo4j vocabulary before invoking.
    """
    if dimension <= 0:
        raise ValueError(f"Invalid vector dimension: {dimension}")
    return (
        f"CREATE VECTOR INDEX {_quote(name)} IF NOT EXISTS "
        f"FOR (n:{_quote(label)}) ON n.{_quote(field)} "
        f"OPTIONS {{ indexConfig: {{ "
        f"`vector.dimensions`: {int(dimension)}, "
        f"`vector.similarity_function`: '{metric}' }} }}"
    )


def build_vector_index_drop(name: str) -> str:
    """``DROP INDEX <name> IF EXISTS``.

    Vector indexes share the index namespace; the same DROP works.
    """
    return f"DROP INDEX {_quote(name)} IF EXISTS"

View on GitHub (pinned to e84aa99b32)

Solutions

Pass the actual embedding dimension, e.g. 384 or 1536.
Validate dimension > 0 at config load time before calling.
Ensure the VectorSchemaProvider/dimension source is initialized before index creation.

Example fix

// before
build_vector_index_create("vec_idx", "Document", "embedding", 0, "cosine")
// after
build_vector_index_create("vec_idx", "Document", "embedding", 768, "cosine")

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try:
    stmt = build_vector_index_create(name, label, field, dim, metric)
except ValueError as e:
    raise RuntimeError("vector index misconfigured: embedding dimension unset") from e

Prevention

Load the embedding model before reading its dimension for config
Centralize the dimension constant rather than scattering literals
Validate dimension at app startup, not at index creation

When it happens

Trigger: Calling build_vector_index_create with dimension=0 or a negative value — e.g. a dimension read from an uninitialized embedding config, a defaulted-to-zero variable, or a VectorSchemaProvider whose size was never set.

Common situations: Embedding model dimension not yet configured (placeholder 0); reading dimension from a config file with a missing/zero value; arithmetic computing dimension (e.g. dim * scale) yielding 0 or negative.

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