cocoindex-io/cocoindex · error · ValueError

Invalid vector dimension: {dimension}

Error message

Invalid vector dimension: {dimension}

What it means

`TableTarget.declare_vector_index` validates the `dimension` argument before declaring the index target state. FalkorDB vector indexes require a positive dimension; a zero or negative value would create an invalid index spec, so ValueError is raised.

Source

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

            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", "ip"] = "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"idx_{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 FalkorDB relationship type."""

View on GitHub (pinned to e84aa99b32)

Solutions

1. Pass the actual embedding dimension, e.g. `declare_vector_index(field="embedding", metric="cosine", dimension=384)`.
2. Match the dimension to the column's `VectorSchemaProvider(dimension=...)` value.
3. Assert `dim > 0` before calling when the value is computed.

Example fix

// before
target.declare_vector_index(field="embedding", dimension=dim)  # dim == 0
// after
assert dim > 0
target.declare_vector_index(field="embedding", dimension=dim)

assert dimension > 0, f"vector index dimension must be positive, got {dimension}"
target.declare_vector_index(field="embedding", metric="cosine", dimension=dimension)

try:
    target.declare_vector_index(field="embedding", dimension=dim)
except ValueError as e:
    if "Invalid vector dimension" in str(e):
        logging.error("Fix dimension source (config/model metadata): %s", e)
    raise

When it happens

Trigger: Calling `target.declare_vector_index(field="embedding", dimension=0)` or a negative/derived-zero dimension — e.g. dimension read from an unset config or `len` of an empty list.

Common situations: Dimension computed from a model config that failed to load; placeholder 0 left in test code (as in the test that exercises this path); mismatch between the vector column's schema dimension and the index dimension.

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 vector dimension: {dimension}
• Invalid vector dimension: {vector_schema.size}
• expected None{loc}, got {type(value).__name__}
• expected {tp}{loc}, got {type(value).__name__}: {value!r}
• expected tuple{loc}, got {type(value).__name__}

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