Pinecone diagnosis: metadata filter matches nothing

TL;DR: Symptom: query with a filter returns empty but unfiltered query works. Check field names, value types, and operator shapes; one wrong type poisons the whole filter. Confirm it 1. Fetch a known record and print its metadata keys and value types.

The error

query with a filter returns empty but unfiltered query works. Check field names, value types, and operator shapes; one wrong type poisons the whole filter. Confirm it 1. Fetch a known record and print its metadata keys and value types.

The fix

1. Fetch a known record and print its metadata keys and value types.
2. Compare each filter clause against those exact keys and types.
3. Test clauses one at a time: add them incrementally until matches vanish; the last clause added is the culprit.
4. Check operator shapes: $in needs a list, $gt needs a number, $exists needs a boolean.
5. Fix the field name or type to match what is actually stored.
6. If metadata was stored with inconsistent types across records (some string, some number), re-ingest with normalized types.
7. Keep a schema document for metadata fields; filters are only as reliable as the schema.
8. This covers exactly what the title says: Pinecone diagnosis.
9. You are setting this up for the first time, or auditing an existing setup.
10. You want the key gotchas in one place before you start.
11. You are doing a different workflow with Pinecone; these steps are specific to the title above.
12. You need the full reference docs; this is the short path, not the manual.

When to use this

• You are seeing this exact error message; match the block above, not just part of it.
• The failing call matches the scenario in the title: Pinecone diagnosis.
• You want the fastest verified fix before digging through logs.

When not to use this

• Your error text differs from the block above; close cousins often have different causes.
• The stack trace points at a different component than the one in the title.
• You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

• Not pinned to a specific version; follows current Pinecone behavior.

Pinecone's filter-by-metadata guide defines the operators ($eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $and, $or) and their type expectations. Verified against live docs 2026-09-26.