{"record":{"id":"5717555dc55605b2","repo":"cocoindex-io/cocoindex","slug":"invalid-vector-definition-vector-def-571755","errorCode":null,"errorMessage":"Invalid vector definition: {vector_def}","messagePattern":"Invalid vector definition: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/turbopuffer/_target.py","lineNumber":83,"sourceCode":"    )\n\n\nclass _ResolvedVectorDef(msgspec.Struct, frozen=True, tag=True):\n    \"\"\"Resolved single (unnamed) vector specification.\"\"\"\n\n    schema: res_schema.VectorSchema\n\n\nclass _ResolvedNamedVectorsDef(msgspec.Struct, frozen=True, tag=True):\n    \"\"\"Resolved named vectors specification (multiple named vectors per namespace).\"\"\"\n\n    vectors: dict[str, _ResolvedVectorDef]\n\n\nasync def _resolve_vector_def(vector_def: VectorDef) -> _ResolvedVectorDef:\n    vs = await res_schema.get_vector_schema(vector_def.schema)\n    if vs is None:\n        raise ValueError(f\"Invalid vector definition: {vector_def}\")\n    # Validate dtype upfront so bad schemas fail at construction time, not on\n    # the first write. Discards the return — used for its raise side effect.\n    _vector_type_str(vs)\n    return _ResolvedVectorDef(schema=vs)\n\n\n# Default vector field name in turbopuffer for an unnamed vector.\n_DEFAULT_VECTOR_FIELD = \"vector\"\n\n# Field names that cannot be used as named vector fields — they would collide\n# with turbopuffer's row id at the wire level.\n_RESERVED_VECTOR_FIELD_NAMES = frozenset({\"id\"})\n\n\n@dataclass(slots=True)\nclass NamespaceSchema:\n    \"\"\"Schema definition for a Turbopuffer namespace.\n","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/turbopuffer/_target.py#L65-L101","documentation":"`_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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Print/inspect the VectorDef and confirm its `schema` points to a vector schema actually registered in the current run.","Declare the vector schema (e.g. via the embedding/vector type machinery) before constructing the turbopuffer target.","Fix typos in the schema reference and retry.","Also verify the resolved schema's dtype is supported (`_vector_type_str` runs right after this check)."],"exampleFix":"// before\nVector(schema=\"embeeding_vec\", dimension=384)  # typo, unregistered\n// after\nVector(schema=\"embedding_vec\", dimension=384)  # matches the declared schema","handlingStrategy":"validation","validationCode":"vs = await res_schema.get_vector_schema(vector_def.schema)\nif vs is None:\n    raise ValueError(f\"Schema {vector_def.schema!r} not registered before target creation\")","typeGuard":"async def vector_def_resolves(vector_def) -> bool:\n    from cocoindex.connectors.turbopuffer import _target\n    return await res_schema.get_vector_schema(vector_def.schema) is not None","tryCatchPattern":"try:\n    spec = await Target.create(vectors=vector_def, distance=metric)\nexcept ValueError as e:\n    if \"Invalid vector definition\" in str(e):\n        raise RuntimeError(f\"Vector schema {vector_def.schema!r} is not registered in this run\") from e\n    raise","preventionTips":["Declare the vector schema in the same environment/lifespan where the target is created.","Keep schema names in constants shared between declaration and use sites.","Check dtype support for the schema before constructing the target."],"tags":["python","schema","vector","turbopuffer"],"backgroundTag":"schema-validation-failed","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"}