cocoindex-io/cocoindex · error · ValueError

Vector field name {sorted(reserved)[0]!r} is reserved (it co

Error message

Vector field name {sorted(reserved)[0]!r} is reserved (it collides with the row id at the wire level).

What it means

Turbopuffer encodes the row id and vector field names into a shared wire namespace, so certain names (in `_RESERVED_VECTOR_FIELD_NAMES`, e.g. the id field name) cannot be used as vector field names. `create()` intersects the caller's dict keys with the reserved set and raises ValueError naming the first colliding key.

Source

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

        Args:
            vectors: Either a single ``VectorDef`` (for an unnamed vector stored
                under turbopuffer's default ``"vector"`` field) or a dict mapping
                vector field names to ``VectorDef`` (for named vectors).
            distance: Distance metric applied to all vector columns in the namespace.
                Default: ``"cosine_distance"``.
        """
        resolved: _ResolvedVectorDef | _ResolvedNamedVectorsDef
        if isinstance(vectors, VectorDef):
            resolved = await _resolve_vector_def(vectors)
        elif isinstance(vectors, dict):
            if not vectors:
                raise ValueError(
                    "Named-vectors dict is empty; declare at least one vector field."
                )
            reserved = _RESERVED_VECTOR_FIELD_NAMES & set(vectors)
            if reserved:
                raise ValueError(
                    f"Vector field name {sorted(reserved)[0]!r} is reserved "
                    f"(it collides with the row id at the wire level)."
                )
            resolved = _ResolvedNamedVectorsDef(
                vectors={
                    name: await _resolve_vector_def(vd) for name, vd in vectors.items()
                }
            )
        else:
            raise ValueError(f"Invalid vector definition: {vectors}")
        return cls(resolved, distance)

    @property
    def vectors(self) -> _ResolvedVectorDef | _ResolvedNamedVectorsDef:
        return self._vectors

    @property
    def distance(self) -> DistanceMetric:

View on GitHub (pinned to e84aa99b32)

Solutions

1. Rename the vector field to a non-reserved name (e.g. `"embedding"` instead of `"id"`).
2. Check `_RESERVED_VECTOR_FIELD_NAMES` in the module to see the full forbidden list.
3. If the name comes from generated config, add a guard that skips or renames reserved keys.

Example fix

// before
vectors={"id": VectorDef(schema="emb", dimension=384)}
// after
vectors={"embedding": VectorDef(schema="emb", dimension=384)}

RESERVED = {"id"}  # mirror of _RESERVED_VECTOR_FIELD_NAMES
bad = RESERVED & set(vectors)
if bad:
    raise ValueError(f"Rename vector field(s): {sorted(bad)} are reserved")

def vector_names_valid(vectors: dict) -> bool:
    from cocoindex.connectors.turbopuffer._target import _RESERVED_VECTOR_FIELD_NAMES
    return not (_RESERVED_VECTOR_FIELD_NAMES & set(vectors))

try:
    spec = await Target.create(vectors=vecs, distance=metric)
except ValueError as e:
    if "is reserved" in str(e):
        raise RuntimeError("Rename the vector field; it collides with the wire-level row id") from e
    raise

When it happens

Trigger: Calling turbopuffer target `create()` with a named-vectors dict containing a key such as `"id"` (any name in `_RESERVED_VECTOR_FIELD_NAMES`).

Common situations: Naming a vector field after the row key by habit; deriving field names from column names where one column is `id`; copying schemas between vector databases with different reserved-name rules.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Invalid vector definition: {vector_def}
• Named-vectors dict is empty; declare at least one vector fie
• Invalid vector definition: {vectors}
• Row {row.id!r}: schema declares named vectors ({sorted(vecto
• Row {row.id!r}: missing vector fields {sorted(missing)}.

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