cocoindex-io/cocoindex · error · ValueError

Invalid vector definition: {vector_def}

Error message

Invalid vector definition: {vector_def}

What it means

`_resolve_vector_def` looks up the vector schema referenced by a `VectorDef` via `res_schema.get_vector_schema`. When the lookup returns None — the schema name/content doesn't resolve to a registered vector schema — it raises ValueError with the rejected definition. This is a construction-time schema validation so bad vectors fail early rather than on first write.

Source

Thrown at python/cocoindex/connectors/turbopuffer/_target.py:83

    )


class _ResolvedVectorDef(msgspec.Struct, frozen=True, tag=True):
    """Resolved single (unnamed) vector specification."""

    schema: res_schema.VectorSchema


class _ResolvedNamedVectorsDef(msgspec.Struct, frozen=True, tag=True):
    """Resolved named vectors specification (multiple named vectors per namespace)."""

    vectors: dict[str, _ResolvedVectorDef]


async def _resolve_vector_def(vector_def: VectorDef) -> _ResolvedVectorDef:
    vs = await res_schema.get_vector_schema(vector_def.schema)
    if vs is None:
        raise ValueError(f"Invalid vector definition: {vector_def}")
    # Validate dtype upfront so bad schemas fail at construction time, not on
    # the first write. Discards the return — used for its raise side effect.
    _vector_type_str(vs)
    return _ResolvedVectorDef(schema=vs)


# Default vector field name in turbopuffer for an unnamed vector.
_DEFAULT_VECTOR_FIELD = "vector"

# Field names that cannot be used as named vector fields — they would collide
# with turbopuffer's row id at the wire level.
_RESERVED_VECTOR_FIELD_NAMES = frozenset({"id"})


@dataclass(slots=True)
class NamespaceSchema:
    """Schema definition for a Turbopuffer namespace.

View on GitHub (pinned to e84aa99b32)

Solutions

1. Print/inspect the VectorDef and confirm its `schema` points to a vector schema actually registered in the current run.
2. Declare the vector schema (e.g. via the embedding/vector type machinery) before constructing the turbopuffer target.
3. Fix typos in the schema reference and retry.
4. Also verify the resolved schema's dtype is supported (`_vector_type_str` runs right after this check).

Example fix

// before
Vector(schema="embeeding_vec", dimension=384)  # typo, unregistered
// after
Vector(schema="embedding_vec", dimension=384)  # matches the declared schema

vs = await res_schema.get_vector_schema(vector_def.schema)
if vs is None:
    raise ValueError(f"Schema {vector_def.schema!r} not registered before target creation")

async def vector_def_resolves(vector_def) -> bool:
    from cocoindex.connectors.turbopuffer import _target
    return await res_schema.get_vector_schema(vector_def.schema) is not None

try:
    spec = await Target.create(vectors=vector_def, distance=metric)
except ValueError as e:
    if "Invalid vector definition" in str(e):
        raise RuntimeError(f"Vector schema {vector_def.schema!r} is not registered in this run") from e
    raise

When it happens

Trigger: Passing a `VectorDef` whose `schema` cannot be resolved (unregistered/mistyped schema reference, schema declared in a different context/lifespan, or a malformed VectorDef) into the turbopuffer target's vector configuration, either directly or through the named-vectors dict.

Common situations: Typo in the schema identifier; referencing a vector schema that was never declared on the source; moving code so the schema is registered under a different environment.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• VectorSchemaProvider is required for NumPy ndarray type.
• VectorSchemaProvider is required for NumPy ndarray type.
• VectorSchemaProvider is only supported for NumPy ndarray typ
• Named-vectors dict is empty; declare at least one vector fie
• Vector field name {sorted(reserved)[0]!r} is reserved (it co

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