{"record":{"id":"98805f21c2a405ed","repo":"cocoindex-io/cocoindex","slug":"vector-field-name-sorted-reserved-0-r-is-reser","errorCode":null,"errorMessage":"Vector field name {sorted(reserved)[0]!r} is reserved (it collides with the row id at the wire level).","messagePattern":"Vector field name (.+?) is reserved \\(it collides with the row id at the wire level\\)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/turbopuffer/_target.py","lineNumber":151,"sourceCode":"\n        Args:\n            vectors: Either a single ``VectorDef`` (for an unnamed vector stored\n                under turbopuffer's default ``\"vector\"`` field) or a dict mapping\n                vector field names to ``VectorDef`` (for named vectors).\n            distance: Distance metric applied to all vector columns in the namespace.\n                Default: ``\"cosine_distance\"``.\n        \"\"\"\n        resolved: _ResolvedVectorDef | _ResolvedNamedVectorsDef\n        if isinstance(vectors, VectorDef):\n            resolved = await _resolve_vector_def(vectors)\n        elif isinstance(vectors, dict):\n            if not vectors:\n                raise ValueError(\n                    \"Named-vectors dict is empty; declare at least one vector field.\"\n                )\n            reserved = _RESERVED_VECTOR_FIELD_NAMES & set(vectors)\n            if reserved:\n                raise ValueError(\n                    f\"Vector field name {sorted(reserved)[0]!r} is reserved \"\n                    f\"(it collides with the row id at the wire level).\"\n                )\n            resolved = _ResolvedNamedVectorsDef(\n                vectors={\n                    name: await _resolve_vector_def(vd) for name, vd in vectors.items()\n                }\n            )\n        else:\n            raise ValueError(f\"Invalid vector definition: {vectors}\")\n        return cls(resolved, distance)\n\n    @property\n    def vectors(self) -> _ResolvedVectorDef | _ResolvedNamedVectorsDef:\n        return self._vectors\n\n    @property\n    def distance(self) -> DistanceMetric:","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/turbopuffer/_target.py#L133-L169","documentation":"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.","triggerScenarios":"Calling turbopuffer target `create()` with a named-vectors dict containing a key such as `\"id\"` (any name in `_RESERVED_VECTOR_FIELD_NAMES`).","commonSituations":"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.","solutions":["Rename the vector field to a non-reserved name (e.g. `\"embedding\"` instead of `\"id\"`).","Check `_RESERVED_VECTOR_FIELD_NAMES` in the module to see the full forbidden list.","If the name comes from generated config, add a guard that skips or renames reserved keys."],"exampleFix":"// before\nvectors={\"id\": VectorDef(schema=\"emb\", dimension=384)}\n// after\nvectors={\"embedding\": VectorDef(schema=\"emb\", dimension=384)}","handlingStrategy":"validation","validationCode":"RESERVED = {\"id\"}  # mirror of _RESERVED_VECTOR_FIELD_NAMES\nbad = RESERVED & set(vectors)\nif bad:\n    raise ValueError(f\"Rename vector field(s): {sorted(bad)} are reserved\")","typeGuard":"def vector_names_valid(vectors: dict) -> bool:\n    from cocoindex.connectors.turbopuffer._target import _RESERVED_VECTOR_FIELD_NAMES\n    return not (_RESERVED_VECTOR_FIELD_NAMES & set(vectors))","tryCatchPattern":"try:\n    spec = await Target.create(vectors=vecs, distance=metric)\nexcept ValueError as e:\n    if \"is reserved\" in str(e):\n        raise RuntimeError(\"Rename the vector field; it collides with the wire-level row id\") from e\n    raise","preventionTips":["Prefix vector fields (e.g. `vec_...`, `embedding`) so they never collide with reserved names.","Never name a vector field `id` or match it to the row key.","Check _RESERVED_VECTOR_FIELD_NAMES when porting schemas from other vector DBs."],"tags":["python","naming","vector","turbopuffer"],"backgroundTag":"invalid-argument-value","analyzedSha":"e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b","analyzedAt":"2026-09-08T15:59:19.997Z","contentChangedAt":"2026-09-08T15:59:19.997Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}