headroomlabs-ai/headroom · error · ValueError

Query vector dimension {query_vector.shape[0]} does not matc

Error message

Query vector dimension {query_vector.shape[0]} does not match index dimension {self._dimension}

What it means

Raised by HNSWVectorIndex.search when the provided query_vector length does not equal the index's dimension. The HNSW graph computes distances in a fixed-dimensional space, so a mismatched query vector cannot be compared against indexed entries.

Source

Thrown at headroom/memory/adapters/hnsw.py:599

        Returns:
            List of search results sorted by similarity (descending).

        Raises:
            ValueError: If neither query_vector nor query_text is provided,
                       or if query_text is provided (embedding must be done externally).
        """
        if filter.query_vector is None:
            if filter.query_text is not None:
                raise ValueError(
                    "query_text provided but HNSWVectorIndex does not embed text. "
                    "Provide query_vector directly or use an Embedder first."
                )
            raise ValueError("Either query_vector or query_text must be provided")

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

        with self._lock:
            # NOTE: Use len() directly, not self.size - Lock is not reentrant!
            current_size = len(self._memory_to_hnsw)
            if current_size == 0:
                return []

            # Search with more results than needed to account for filtering
            # Retrieve extra candidates to improve recall after filtering
            k_with_buffer = min(
                filter.top_k * 10,  # Get 10x candidates for filtering
                current_size,  # But not more than we have
            )

            # Query HNSW index

View on GitHub (pinned to 322425c43b)

Solutions

1. Verify len(query_vector) == index dimension (exposed via the index's dimension property) before searching.
2. If the embedder changed, rebuild the index so both dimensions agree.
3. Log the offending vector's shape at the call site to catch upstream reshape bugs.

Example fix

// before
results = await index.search(VectorFilter(query_vector=vec))  # len(vec)=384, index=768

// after
assert len(vec) == index.dimension, f"{len(vec)} != {index.dimension}"
results = await index.search(VectorFilter(query_vector=vec))

if len(filter.query_vector) != index.dimension:
    raise ValueError(f"query dim {len(filter.query_vector)} != {index.dimension}")

When it happens

Trigger: Searching an index built for one embedding model with vectors from another; hand-constructed query vectors of the wrong length; truncation or reshaping bugs upstream that alter vector length.

Common situations: Switching embedder models after the index was built; using a pooled/averaged vector with unexpected shape; a stale index file loaded with a new default dimension.

Related errors

• Embedding dimension {embedding.shape[0]} does not match inde
• query_text provided but HNSWVectorIndex does not embed text.
• Either query_vector or query_text must be provided
• Query dimension {query_vector.shape[0]} does not match index
• Memory {memory.id} has no embedding

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