cocoindex-io/cocoindex · error · ValueError

Qdrant named vectors must not be empty

Error message

Qdrant named vectors must not be empty

What it means

Raised in `create` when the `vectors` dict is empty. A Qdrant collection built from a schema must declare at least one vector; an empty named-vectors dict has nothing to create and is rejected explicitly rather than producing a broken collection.

Source

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

        Args:
            vectors: Either a single QdrantVectorDef (for an unnamed dense
                     vector) or a dictionary mapping vector names to
                     QdrantVectorDef or QdrantSparseVectorDef. Dense and
                     sparse vectors share one namespace in Qdrant, so both
                     kinds live in the same dict; sparse vectors are always
                     named.
        """
        resolved: _ResolvedQdrantVectorDef | _ResolvedQdrantNamedVectorsDef
        if isinstance(vectors, QdrantVectorDef):
            resolved = await _resolve_vector_def(vectors)
        elif isinstance(vectors, QdrantSparseVectorDef):
            raise ValueError(
                "Qdrant sparse vectors are always named; pass them in a dict, "
                '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}")

View on GitHub (pinned to e84aa99b32)

Solutions

1. Pass at least one named vector definition, e.g. `vectors={"dense": QdrantVectorDef(...)}`.
2. If no vector is needed, don't create a vector-based collection for this schema.
3. Fix the upstream code that produces the empty dict (log its contents before create).

Example fix

// before
create(vectors={})
// after
create(vectors={"dense": QdrantVectorDef(dimension=768, distance=QdrantDistance.COSINE)})

def require_vectors(vectors: dict) -> dict:
    if not vectors:
        raise ValueError("At least one named vector required")
    return vectors

def has_vectors(v) -> bool:
    return isinstance(v, dict) and len(v) > 0 or hasattr(v, 'dimension')

try:
    collection = await QdrantCollection.create(..., vectors=vector_defs)
except ValueError as e:
    if "must not be empty" in str(e):
        logger.error("vector_defs built empty: %r", vector_defs)
    else:
        raise

When it happens

Trigger: Calling `create(vectors={})` — often the result of building the dict programmatically from a filter that matched nothing.

Common situations: Generating vector defs from config where the vector list was accidentally filtered out; a bug upstream that yields an empty mapping; deleting all vectors from a collection definition without removing the collection.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Qdrant collection schema must declare at least one vector
• qdrant-client is required to use the Qdrant connector. Pleas
• Invalid vector definition: {vector_def}
• Qdrant sparse vectors are always named; pass them in a dict,
• Invalid vector definition: {vectors}

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