{"record":{"id":"3288568270a6d2fe","repo":"cocoindex-io/cocoindex","slug":"qdrant-sparse-vectors-are-always-named-pass-them","errorCode":null,"errorMessage":"Qdrant sparse vectors are always named; pass them in a dict, e.g. vectors={\"sparse\": QdrantSparseVectorDef()}","messagePattern":"Qdrant sparse vectors are always named; pass them in a dict, e\\.g\\. vectors=(.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/qdrant/_target.py","lineNumber":200,"sourceCode":"        | dict[str, QdrantVectorDef | QdrantSparseVectorDef]\n        | None = None,\n    ) -> \"CollectionSchema\":\n        \"\"\"\n        Create a CollectionSchema by resolving vector definitions.\n\n        Args:\n            vectors: Either a single QdrantVectorDef (for an unnamed dense\n                     vector) or a dictionary mapping vector names to\n                     QdrantVectorDef or QdrantSparseVectorDef. Dense and\n                     sparse vectors share one namespace in Qdrant, so both\n                     kinds live in the same dict; sparse vectors are always\n                     named.\n        \"\"\"\n        resolved: _ResolvedQdrantVectorDef | _ResolvedQdrantNamedVectorsDef\n        if isinstance(vectors, QdrantVectorDef):\n            resolved = await _resolve_vector_def(vectors)\n        elif isinstance(vectors, QdrantSparseVectorDef):\n            raise ValueError(\n                \"Qdrant sparse vectors are always named; pass them in a dict, \"\n                'e.g. vectors={\"sparse\": QdrantSparseVectorDef()}'\n            )\n        elif isinstance(vectors, dict):\n            if not vectors:\n                raise ValueError(\"Qdrant named vectors must not be empty\")\n            _validate_vector_names(vectors.keys(), \"vector\")\n            resolved_entries: dict[\n                str, _ResolvedQdrantVectorDef | _ResolvedQdrantSparseVectorDef\n            ] = {}\n            for name, vector_def in vectors.items():\n                if isinstance(vector_def, QdrantVectorDef):\n                    resolved_entries[name] = await _resolve_vector_def(vector_def)\n                elif isinstance(vector_def, QdrantSparseVectorDef):\n                    resolved_entries[name] = _resolve_sparse_vector_def(vector_def)\n                else:\n                    raise ValueError(f\"Invalid vector definition: {vector_def}\")\n            resolved = _ResolvedQdrantNamedVectorsDef(vectors=resolved_entries)","sourceCodeStart":182,"sourceCodeEnd":218,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/qdrant/_target.py#L182-L218","documentation":"Raised in `create` when a bare `QdrantSparseVectorDef` is passed as `vectors`. Qdrant sparse vectors must live under a name; unnamed (single, default) vectors only support dense vectors. The fix is to wrap the sparse definition in a dict with an explicit name.","triggerScenarios":"Calling collection `create(vectors=QdrantSparseVectorDef())` without wrapping it in a named dict.","commonSituations":"Porting code that used a dense default vector to sparse vectors; assuming sparse vectors follow the same single-default-vector API as dense ones.","solutions":["Wrap the sparse definition in a dict: `vectors={\"sparse\": QdrantSparseVectorDef()}`.","Choose a meaningful name — points must supply their sparse vectors under that same name."],"exampleFix":"// before\ncreate(vectors=QdrantSparseVectorDef())\n// after\ncreate(vectors={\"sparse\": QdrantSparseVectorDef()})","handlingStrategy":"type-guard","validationCode":"def vectors_arg_ok(vectors) -> bool:\n    from cocoindex.connectors.qdrant._target import QdrantVectorDef, QdrantSparseVectorDef\n    if isinstance(vectors, QdrantSparseVectorDef):\n        return False\n    return True","typeGuard":"def is_valid_vectors_arg(v) -> bool:\n    from cocoindex.connectors.qdrant import QdrantVectorDef, QdrantSparseVectorDef\n    return isinstance(v, QdrantVectorDef) or (isinstance(v, dict) and bool(v))","tryCatchPattern":"try:\n    collection = await QdrantCollection.create(..., vectors=vectors)\nexcept ValueError as e:\n    if \"sparse vectors are always named\" in str(e):\n        vectors = {\"sparse\": vectors}  # wrap and retry\n        collection = await QdrantCollection.create(..., vectors=vectors)\n    else:\n        raise","preventionTips":["Always use the named-dict form for sparse vectors.","Wrap vector construction in a helper that returns valid args only.","Note the API difference: dense can be unnamed, sparse cannot."],"tags":["qdrant","sparse-vectors","api-usage"],"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"}