Support

Troubleshooting Guide

Step-by-step instructions for debugging search quality, database connection errors, performance issues, and hosting environments.

Operations guide · Finkkle documentation

Search Quality & Zero-Result Issues

If queries yield empty listings or lack relevance, verify crawler, FTS, and PageRank status:

Check index totals via the stats API: GET /api/stats.
If the database has content but text searches fail, rebuild FTS indices:
```
npm run rebuild-images-fts
```
Verify page link structures are computed. Run the post-crawl updates to refresh PageRank and domain authorities:
```
npm run post-crawl
```
Execute quality evaluation checks to score current relevance metrics against test gold sets:
```
npm run phase7:eval
```

Database failures can occur when switching environments or during configuration changes:

Local SQLite (search.db): Ensure the file search.db exists in the project root and is readable by the Node process. Run the database verification script:
```
node check_db.js
```
Remote Turso / libSQL: Check that TURSO_DATABASE_URL and TURSO_AUTH_TOKEN are correctly assigned in your environment. Test connectivity by running the database migration checks.

Finkkle runs on two primary host frameworks, each requiring specific configurations:

Uses api/index.js bridge to run the Fastify server serverlessly.

Local DB limitation: SQLite files are not supported in serverless directories because the filesystem is read-only and ephemeral. You must configure a remote Turso database instance.
Environment check: Ensure Turso and Supabase environment variables are published on the Vercel project dashboard.

Runs the compiled TypeScript server via ecosystem.config.js.

Process status: Monitor the active instance list using:
```
pm2 status
```
Runtime logging: Print real-time server output or uncaught exception logs using:
```
pm2 logs
```

If responses show stale content or high load times, check the cache layer:

Clear stored Redis and memory records:
```
npm run clear-cache
```
Check Redis connection variables (e.g. REDIS_URL). If Redis is unreachable, the server falls back to local in-memory caching.