{"record":{"id":"e692d2e51722b267","repo":"cocoindex-io/cocoindex","slug":"named-vectors-dict-is-empty-declare-at-least-one","errorCode":null,"errorMessage":"Named-vectors dict is empty; declare at least one vector field.","messagePattern":"Named-vectors dict is empty; declare at least one vector field\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/turbopuffer/_target.py","lineNumber":146,"sourceCode":"        vectors: VectorDef | dict[str, VectorDef],\n        *,\n        distance: DistanceMetric = \"cosine_distance\",\n    ) -> \"NamespaceSchema\":\n        \"\"\"Create a NamespaceSchema by resolving vector definitions.\n\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","sourceCodeStart":128,"sourceCodeEnd":164,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/turbopuffer/_target.py#L128-L164","documentation":"Turbopuffer's named-vectors mode requires at least one vector field per row schema. When `create()` is given an empty dict as `vectors`, it raises ValueError because a rows-with-named-vectors setup with zero vectors is meaningless.","triggerScenarios":"Calling the turbopuffer target `create()` with `vectors={}` (an empty dict) instead of a `VectorDef` or a non-empty dict.","commonSituations":"Building the vectors dict programmatically from config that ended up empty; filtering out all vector fields by mistake; default-argument misuse.","solutions":["Pass at least one entry in the vectors dict, e.g. `vectors={\"embedding\": VectorDef(...)}`.","If you meant a single unnamed vector, pass a `VectorDef` instance directly instead of a dict.","Check the code that constructs the dict — an upstream filter or config may be dropping all fields."],"exampleFix":"// before\nspec = await TurbopufferTarget.create(vectors={}, distance=Metric.cosine)\n// after\nspec = await TurbopufferTarget.create(vectors={\"embedding\": VectorDef(schema=\"embedding_vec\", dimension=384)}, distance=Metric.cosine)","handlingStrategy":"validation","validationCode":"if isinstance(vectors, dict) and not vectors:\n    raise ValueError(\"vectors dict must contain at least one VectorDef\")","typeGuard":"def has_named_vectors(vectors) -> bool:\n    return isinstance(vectors, dict) and len(vectors) > 0","tryCatchPattern":"try:\n    spec = await Target.create(vectors=vectors_dict, distance=metric)\nexcept ValueError as e:\n    if \"Named-vectors dict is empty\" in str(e):\n        raise RuntimeError(\"No vector fields configured for turbopuffer target\") from e\n    raise","preventionTips":["Assert the vectors dict is non-empty right after building it from config.","Fall back to a single VectorDef when only one vector field exists.","Add a startup check that every target has at least one declared vector field."],"tags":["python","vector","validation","turbopuffer"],"backgroundTag":"empty-required-field","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"}