cocoindex-io/cocoindex · error · ValueError

Invalid vector dimension for {name!r}: {vector_schema.size}

Error message

Invalid vector dimension for {name!r}: {vector_schema.size}

What it means

Raised in _resolve_column while translating a record field into a zvec column schema. A dense-vector column (np.ndarray with a VectorSchema annotation) must have a valid positive dimension; the size comes from VectorSchema resolved via the field's annotations or a column override. When that size is invalid, no corresponding zvec vector type can be built, so this ValueError fires for the named column. Provide a VectorSchema with a positive dimension.

Source

Thrown at python/cocoindex/connectors/zvec/_target.py:368

    if override is not None:
        annotations.append(override)
    annotations.extend(type_info.annotations)

    vector_schema: res_schema.VectorSchema | None = None
    for annot in annotations:
        vs = await res_schema.get_vector_schema(annot)
        if vs is not None:
            vector_schema = vs
            break

    vector_def = next((a for a in annotations if isinstance(a, ZvecVectorDef)), None)
    zvec_type = next((a for a in annotations if isinstance(a, ZvecType)), None)
    fts_type = next((a for a in annotations if isinstance(a, ZvecFtsType)), None)

    # Dense vector: NumPy ndarray with a VectorSchema.
    if vector_schema is not None:
        if vector_schema.size <= 0:
            raise ValueError(
                f"Invalid vector dimension for {name!r}: {vector_schema.size}"
            )
        vd = vector_def or ZvecVectorDef()
        return _Column(
            name=name,
            kind="dense",
            data_type=_dense_vector_data_type(vector_schema.dtype),
            nullable=type_info.nullable,
            dimension=vector_schema.size,
            metric=vd.metric,
            quantize=vd.quantize,
        )

    # Sparse vector: explicitly marked via ZvecVectorDef(sparse=True).
    if vector_def is not None and vector_def.sparse:
        return _Column(
            name=name,
            kind="sparse",

View on GitHub (pinned to e84aa99b32)

Solutions

1. Set VectorSchema.size to the actual embedding dimension (e.g. 768, 1536)
2. Ensure the dimension variable is resolved before from_class is called
3. Validate size > 0 in your own config loading

Example fix

// before
Annotated[np.ndarray, VectorSchema(size=0)]
// after
Annotated[np.ndarray, VectorSchema(size=768)]

assert size > 0, "VectorSchema.size must be positive; set it to the embedding dimension"

try:
    schema = ZvecCollection.from_class(Row)
except ValueError as e:
    if "Invalid vector dimension" in str(e):
        raise ConfigError("Fix VectorSchema.size in your row class") from e
    raise

When it happens

Trigger: Annotating an ndarray column with VectorSchema(size=0) or a negative size, or computing size from an empty/unset variable, when calling from_class.

Common situations: Embedding dimension not yet known at declaration time (placeholder 0); a config variable that failed to resolve; copy-paste leaving size 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

• Vector column {name!r} requires a VectorSchema (provide it v
• Invalid vector dimension: {vector_schema.size}
• Invalid vector dimension: {vector_schema.size}
• Named-vectors dict is empty; declare at least one vector fie
• Invalid {kind}: {name!r}

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