Debugging Common Issues
1. Debugging Connection Failures
| Symptom | Check |
|---|
| 401 | API key correct, not revoked |
| DNS / SSL | Firewall / proxy / TLS |
| Wrong host | Re-read index host from describe_index |
2. Debugging Dimension Mismatches
Example: Validate Before Upsert
dim = pc.describe_index("docs").dimension
for v in vectors:
assert len(v["values"]) == dim, f"Expected {dim}, got {len(v['values'])}"
| Cause | Fix |
|---|
| Type mismatch | Filter type must match stored type |
| Unsupported op | Check operator list |
| Nested object | Flatten — Pinecone supports flat keys |
4. Debugging Empty Query Results
| Possible Cause | Test |
|---|
| Wrong namespace | Query without filter/ns first |
| Filter too narrow | Remove filter; rerun |
| Index empty | describe_index_stats() |
| Eventual consistency | Wait a few seconds |
5. Debugging Slow Queries
| Cause | Fix |
|---|
| Cold serverless | Warm-up query |
| High fullness | Scale |
| Expensive filter | Lower cardinality |
| Large top_k | Reduce |
6. Debugging Authentication Errors
| Step | Detail |
|---|
| 1. Verify key | Console → API keys |
| 2. Right project | Index lives in same project as key |
| 3. Env var loaded | Print first 4 chars |
7. Debugging Quota Errors
| Error | Action |
|---|
| Pod quota exceeded | Delete unused index or upgrade plan |
| Index count exceeded | Same |
| Region not available | Choose different region |
8. Debugging Upsert Failures
| Cause | Fix |
|---|
| Vector too large | Reduce dim / metadata size (40KB / vector) |
| Bad metadata type | Only str/num/bool/list-of-str |
| Bad ID | ASCII, ≤512 chars |
9. Debugging Namespace Issues
Example: List Namespaces
print(list(index.describe_index_stats()["namespaces"].keys()))
10. Debugging SDK Version Issues
Example: Print Version
import pinecone
print(pinecone.__version__)
Warning: Pinecone deprecated v2 (pinecone-client) in favor of v5+ pinecone package with major API differences.
11. Using Debug Logging
Example: Enable Debug
import logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("pinecone").setLevel(logging.DEBUG)
12. Reproducing Issues
| Capture | For Bug Report |
|---|
| SDK + Python version | Reproducibility |
| Index spec | Dimension, metric, cloud, region |
| Request body | Sample input |
| Full traceback | + HTTP status code |