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

Pass the actual embedding dimension, e.g. dimension=384 for all-MiniLM-L6-v2 or 1536 for OpenAI text-embedding-3-small.

cocoindex-io/cocoindex · error · ValueError

Invalid vector dimension: {dimension}

Error message

Invalid vector dimension: {dimension}

What it means

declare_vector_index() validates that the vector dimension is a positive integer before creating the vector index target state; Neo4j vector indexes require a fixed positive dimension. A dimension <= 0 cannot map to any valid index.

Source

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

            return dict(row)
        record_info = RecordType(type(row))
        return {f.name: getattr(row, f.name) for f in record_info.fields}

    def declare_vector_index(
        self: TableTarget[RowT],
        *,
        name: str | None = None,
        field: str,
        metric: Literal["cosine", "euclidean"] = "cosine",
        dimension: int,
    ) -> None:
        """Declare a vector index on a column of this table."""
        _validate_identifier(field, "vector index field")
        if name is None:
            name = f"vec_{self._table_name}__{field}"
        _validate_identifier(name, "vector index name")
        if dimension <= 0:
            raise ValueError(f"Invalid vector dimension: {dimension}")
        spec = _VectorIndexSpec(field=field, metric=metric, dimension=dimension)
        att_provider = self._provider.attachment("vector_index")
        coco.declare_target_state(att_provider.target_state(name, spec))

    def __coco_memo_key__(self) -> str:
        return self._provider.memo_key


# ---------------------------------------------------------------------------
# RelationTarget
# ---------------------------------------------------------------------------


class RelationTarget(
    Generic[RowT, coco.MaybePendingS], coco.ResolvesTo["RelationTarget[RowT]"]
):
    """A target for writing relation records (edges) to a Neo4j relationship type."""

View on GitHub (pinned to e84aa99b32)

Solutions

Pass the actual embedding dimension, e.g. dimension=384 for all-MiniLM-L6-v2 or 1536 for OpenAI text-embedding-3-small.
Verify the value feeding `dimension` is not 0/None due to a failed config load before calling declare_vector_index.

Example fix

// before
table.declare_vector_index(field="embedding", metric="cosine", dimension=0)
// after
table.declare_vector_index(field="embedding", metric="cosine", dimension=384)

Defensive patterns

Strategy: validation

Validate before calling

EMBED_DIM = 384  # must match your embedding model
assert isinstance(EMBED_DIM, int) and EMBED_DIM > 0
table.declare_vector_index(field="embedding", metric="cosine", dimension=EMBED_DIM)

Try / catch

try:
    table.declare_vector_index(field="embedding", metric="cosine", dimension=dim)
except ValueError as e:
    raise ConfigError(f"vector dimension must be positive, got {dim!r}") from e

Prevention

Define the embedding dimension as a constant shared between the embedder config and declare_vector_index.
Never pass a computed/uninitialized value directly; assert it is a positive int first.

When it happens

Trigger: Calling table.declare_vector_index(field=..., dimension=0) or a negative value, typically when dimension is computed from an embedding config that failed to load or defaulted to 0.

Common situations: Embedding model dimension read from an uninitialized variable, config placeholder like dimension=0, or passing len([]) of an empty example embedding.

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