cocoindex-io/cocoindex · error · ValueError

Qdrant collection schema must declare at least one vector

Error message

Qdrant collection schema must declare at least one vector

What it means

Raised in `create` when `vectors=None`. A Qdrant collection schema must declare at least one vector (dense or sparse); omitting vectors entirely leaves the collection without a vector definition, which this connector forbids.

Source

Thrown at python/cocoindex/connectors/qdrant/_target.py:220

                'e.g. vectors={"sparse": QdrantSparseVectorDef()}'
            )
        elif isinstance(vectors, dict):
            if not vectors:
                raise ValueError("Qdrant named vectors must not be empty")
            _validate_vector_names(vectors.keys(), "vector")
            resolved_entries: dict[
                str, _ResolvedQdrantVectorDef | _ResolvedQdrantSparseVectorDef
            ] = {}
            for name, vector_def in vectors.items():
                if isinstance(vector_def, QdrantVectorDef):
                    resolved_entries[name] = await _resolve_vector_def(vector_def)
                elif isinstance(vector_def, QdrantSparseVectorDef):
                    resolved_entries[name] = _resolve_sparse_vector_def(vector_def)
                else:
                    raise ValueError(f"Invalid vector definition: {vector_def}")
            resolved = _ResolvedQdrantNamedVectorsDef(vectors=resolved_entries)
        elif vectors is None:
            raise ValueError(
                "Qdrant collection schema must declare at least one vector"
            )
        else:
            raise ValueError(f"Invalid vector definition: {vectors}")
        return cls(resolved)

    @property
    def vectors(
        self,
    ) -> _ResolvedQdrantVectorDef | _ResolvedQdrantNamedVectorsDef:
        """Get vector definitions (all VectorSchemaProviders resolved)."""
        return self._vectors


class _PointAction(NamedTuple):
    point_id: _PointId
    point: qdrant_models.PointStruct | None

View on GitHub (pinned to e84aa99b32)

Solutions

1. Pass at least one vector definition, e.g. `vectors=QdrantVectorDef(dimension=768, distance=QdrantDistance.COSINE)` or a named dict.
2. If a truly vector-less Qdrant collection is needed, create it directly with qdrant_client instead of this schema-based connector.
3. Check the code path that leaves `vectors` unset and make it mandatory.

Example fix

// before
create(collection="docs")
// after
create(collection="docs", vectors=QdrantVectorDef(dimension=768, distance=QdrantDistance.COSINE))

def require_vectors_arg(vectors) -> None:
    if vectors is None:
        raise ValueError("vectors must be provided")

from typing import assert_never
def has_vector_decl(v) -> bool:
    return v is not None

try:
    collection = await QdrantCollection.create(..., vectors=vectors)
except ValueError as e:
    if "at least one vector" in str(e):
        logger.error("vectors=None passed; supply a vector definition")
    else:
        raise

When it happens

Trigger: Calling collection `create(...)` without the `vectors` argument or with `vectors=None`.

Common situations: Creating a non-vector collection through the vector-collection API; forgetting the argument after refactoring; conditionally built code paths where vectors were dropped.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Qdrant named vectors must not be empty
• use_mount() requires a ComponentSubpath when the function ha
• mount() requires a ComponentSubpath when the function has no
• mount_each() requires a ComponentSubpath when the function h
• Either async_fn or sync_fn must be provided

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