headroomlabs-ai/headroom · error · ValueError

query_vector must be provided

Error message

query_vector must be provided

What it means

Raised by SQLiteVectorIndex.search when the VectorFilter provides neither query_vector nor query_text. Vector similarity search requires a query; constraint-only filters are not a valid 'list all' request for this backend.

Source

Thrown at headroom/memory/adapters/sqlite_vector.py:666

                conn.commit()
                return len(rowids)

    async def search(self, filter: VectorFilter) -> list[VectorSearchResult]:
        """Search for similar vectors.

        Args:
            filter: Search filter with query vector and constraints.

        Returns:
            List of search results sorted by similarity (descending).
        """
        if filter.query_vector is None:
            if filter.query_text is not None:
                raise ValueError(
                    "query_text provided but SQLiteVectorIndex does not embed text. "
                    "Provide query_vector directly or use an Embedder first."
                )
            raise ValueError("query_vector must be provided")

        query_vector = np.asarray(filter.query_vector, dtype=np.float32)
        if query_vector.shape[0] != self._dimension:
            raise ValueError(
                f"Query dimension {query_vector.shape[0]} does not match "
                f"index dimension {self._dimension}"
            )

        with self._lock:
            with self._get_conn() as conn:
                # sqlite-vec returns distance (lower = more similar for L2)
                # For cosine, we need to convert: similarity = 1 - distance
                # But sqlite-vec's cosine distance is already 1 - cosine_similarity
                # So similarity = 1 - distance

                # Get more results than needed for post-filtering
                k_with_buffer = filter.top_k * 10

View on GitHub (pinned to 322425c43b)

Solutions

1. Require and set a query (embedded to a vector) before calling search.
2. Validate at the request boundary: reject empty queries with a clear error to the client.
3. For non-similarity listing, query the metadata store directly instead of the vector index.

Example fix

// before
results = await index.search(VectorFilter(user_id="u1"))

// after
if not query:
    raise ValueError("query required for vector search")
results = await index.search(VectorFilter(query_vector=await embedder.embed(query), user_id="u1"))

if filter.query_vector is None and filter.query_text is None:
    raise ValueError("query required for similarity search")

When it happens

Trigger: Constructing VectorFilter with only metadata constraints (user_id, session_id, time ranges); a nullable query variable defaulting to None and assigned to neither field.

Common situations: API endpoints where the query is optional but vector search is unconditional; dynamic filter builders omitting the query key; expecting listing semantics from a similarity index.

Related errors

• Either query_vector or query_text must be provided
• query_text provided but SQLiteVectorIndex does not embed tex
• Query dimension {query_vector.shape[0]} does not match index
• query_text provided but HNSWVectorIndex does not embed text.
• Query vector dimension {query_vector.shape[0]} does not matc

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/08351d15fd5cc586. Report an issue: GitHub.