KeyError
builtins.KeyError
Stack trace
Traceback (most recent call last):
File "app.py", line 45, in <module>
results = vector_store.query(filter={'category': 'news'}) # KeyError here
File "/usr/local/lib/python3.9/site-packages/pinecone/client.py", line 123, in query
raise KeyError(f"Metadata filter key '{key}' not found in vector store")
KeyError: "Metadata filter key 'category' not found in vector store" Why it happens
Vector stores like Pinecone require that all metadata filter keys used in queries exist in the indexed documents. If you query with a filter key that was never added to any document's metadata, the vector store raises a KeyError indicating the key is missing.
Detection
Monitor query failures and catch KeyError exceptions when applying metadata filters. Log the filter keys used and verify they exist in your indexed documents' metadata schema.
Causes & fixes
Filtering on a metadata key that was never added to any document during indexing
Ensure that all documents indexed into the vector store include the metadata keys you intend to filter on.
Typo or case mismatch in the metadata filter key compared to the indexed metadata keys
Verify and correct the spelling and casing of filter keys to exactly match the metadata keys used during document indexing.
Using a vector store that enforces strict metadata schema and does not allow querying on unknown keys
Predefine and register all metadata keys with the vector store if required, or avoid filtering on keys not present in the schema.
Code: broken vs fixed
from pinecone import Pinecone
import os
client = Pinecone(api_key=os.environ['PINECONE_API_KEY'])
index = client.Index('my-index')
# This will raise KeyError if 'category' key is missing in metadata
results = index.query(queries=[[0.1, 0.2, 0.3]], filter={'category': 'news'}) # KeyError here
print(results)from pinecone import Pinecone
import os
client = Pinecone(api_key=os.environ['PINECONE_API_KEY'])
index = client.Index('my-index')
# Fix: Ensure 'category' key exists in metadata of all indexed vectors
# Example: Add metadata during upsert
index.upsert(vectors=[('vec1', [0.1, 0.2, 0.3], {'category': 'news'})])
results = index.query(queries=[[0.1, 0.2, 0.3]], filter={'category': 'news'}) # Works now
print(results)Workaround
Catch the KeyError exception when querying and fallback to querying without the metadata filter or with a validated subset of keys.
Prevention
Maintain a consistent metadata schema for all indexed documents and validate filter keys against this schema before querying the vector store.