What causes "dimension is required for declare_vector_index()" in cocoindex-io/cocoindex?

Pass `dimension= ` matching your embedding model's output size (e.g. 384 for all-MiniLM-L6-v2, 1536 for text-embedding-3-small).

cocoindex-io/cocoindex · error · ValueError

dimension is required for declare_vector_index()

Error message

dimension is required for declare_vector_index()

What it means

A vector index in SurrealDB needs an explicit dimension (vector length) to be created. `declare_vector_index()` raises ValueError when `dimension=None` because there is no default the library could safely infer for arbitrary vector fields.

Solutions

Pass `dimension=<int>` matching your embedding model's output size (e.g. 384 for all-MiniLM-L6-v2, 1536 for text-embedding-3-small).
If the vector comes from a cocoindex Vector schema, read the dimension from the embedding function/model config and pass it through.
Check the method signature: `dimension` is required, not defaulted.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

if dimension is None:
    raise ValueError("dimension must be set before declare_vector_index()")
assert isinstance(dimension, int) and dimension > 0

Type guard

def has_dimension(kwargs: dict) -> bool:
    d = kwargs.get("dimension")
    return isinstance(d, int) and d > 0

Try / catch

try:
    await table.declare_vector_index(field="embedding", metric="cosine", dimension=dim)
except ValueError as e:
    if "dimension is required" in str(e):
        raise RuntimeError("Embedding dimension not configured") from e
    raise

Prevention

Derive dimension from your embedding model config and pass it explicitly.
Centralize index creation in one helper that takes dimension as a required parameter.
Validate embedding output length once at startup and reuse it.

When it happens

Trigger: Calling `table.declare_vector_index(field=..., ...)` without the `dimension` keyword argument, or explicitly passing `dimension=None`.

Common situations: Following older documentation or examples where dimension was optional; copying a call for a scalar index and adding a `field` only; assuming the embedding model's dimension is auto-detected.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at python/cocoindex/connectors/surrealdb/_target.py:1139

            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", "manhattan"] = "cosine",
        method: Literal["mtree", "hnsw"] = "mtree",
        dimension: int | None = None,
        vector_type: Literal["f32", "f64", "i16", "i32", "i64"] = "f32",
    ) -> None:
        """Declare a vector index on 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 is None:
            raise ValueError("dimension is required for declare_vector_index()")
        spec = _VectorIndexSpec(
            field=field,
            metric=metric,
            method=method,
            dimension=dimension,
            vector_type=vector_type,
        )
        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
# ---------------------------------------------------------------------------

View on GitHub (pinned to e84aa99b32)