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-init

Verify that the indices required for your chosen Search Tier exist in your database. You can also call engine.verifyIndexes() at startup — it runs EXPLAIN against each active tier's query and flags any sequential scan.

Slow Query Performance

If queries are slower than expected:

1. Check your tier: Ensure you have a GiST/GIN trigram index (gist_trgm_ops/gin_trgm_ops) for >1M rows — not RUM; see the callout in Search Tiers on why the ADVANCED tier's own RUM claim is aspirational.
2. Enable Turbo Mode: Pre-computing tsvector drastically reduces read-time CPU. See Turbo Mode. Note: if searchColumns has more than one column and you haven't set ftsColumn, the engine logs a warning — the CLI only ever generates one GIN index per column, never a matching combined-expression index, so a multi-column on-the-fly to_tsvector search always sequential-scans.
3. Check Cache Hit Rate: Review engine.metrics.getSummary().cacheHitRate. If it's 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.