Troubleshooting

"Relation does not exist" or Missing Index Errors

If you encounter errors related to missing indices or relations, ensure you have run the database initialization:

npx pg-smart-search init

Verify that the indices required for your chosen Search Tier exist in your database.

Slow Query Performance

If queries are slower than expected:

1. Check your tier: Ensure you are using the correct indices for your dataset size (e.g., RUM index for >1M rows).
2. Enable Turbo Mode: Pre-computing tsvector drastically reduces read-time CPU. See Turbo Mode.
3. Check Cache Hit Rate: Review engine.metrics.cacheHitRate. If its low, your cache TTL might be too short, or your query distribution is too wide.

Vector Search 429 Errors

If vector search fails with rate limit errors:

The built-in p-queue should handle rate limiting automatically. If you are still seeing 429 errors, you may need to batch your embedding requests or reduce the concurrency limits in your application logic.

Zombie Queries Consuming DB Resources

pg-smart-search v1.3+ uses AbortController to cancel slow queries. If you are on an older version, upgrade to v1.3+. If you are on v1.3+ and still seeing zombie queries, ensure your database adapter correctly passes the AbortSignal down to the raw driver.