Search docs...
DocsDiagnosticsTroubleshooting

Troubleshooting

Resolving SQLite DLL mismatch errors, database locks, and stalled crawler processes.

3 min read•Edit on GitHub

This guide covers common errors, recovery actions, and diagnostic steps for resolving issues in LeadForge OS.

Application Launch Failures

SQLite Binary DLL Mismatch

  • Symptom: Startup crashes with the error:
    text
    better_sqlite3.node was compiled against a different Node.js version
  • Cause: The native SQLite binary was compiled for the global Node version instead of Electron's internal Node ABI.
  • Solution: Force rebuild native modules for Electron:
    bash
    pnpm -F @leadforge/desktop exec electron-builder install-app-deps

Database & Migration Failures

Stuck or Corrupt Migrations

  • Symptom: Application displays database connection errors on startup, or loops during migrations.
  • Self-Healing Mechanism:
    • The migration runner (runner.ts) copies the SQLite database file to leadforge_${workspaceId}.db.migration.bak before applying migrations.
    • If a migration statement fails, the transaction is rolled back, the connection is closed, and the database is restored from the backup file.
  • Manual Restoration:
    • Open the Operations Center diagnostics tab and select the Restore Backup recovery action.
    • Alternatively, in your workspaces directory, copy the .migration.bak file over your main .db file manually.

Scheduler & Worker Crashes

Worker Heartbeat Timeout

  • Symptom: Long-running scraper jobs change status from running to failed with the error Worker process lost heartbeat.
  • Cause: The child worker process failed to respond to the scheduler's ping within 30 seconds (due to out-of-memory or system sleep).
  • Solution:
    • Check the Error Console in the Operations Center.
    • If the worker crashed due to memory bounds (e.g. Playwright scrolling infinite listings), split your scrape query into smaller geographical locations.
    • Click the Retry Job action in the Cockpit to requeue.

Sync Engine Failures

Queue Stalling

  • Symptom: Locally modified companies or contacts do not appear on your Hono server dashboard, and the sync queue grows.
  • Diagnosis:
    • Review the lastError column in the sync_queue table or check the Sync Engine Status in the Operations Center.
    • Ensure that the Hono API server (apps/api/) is running and accessible:
      bash
      curl http://localhost:3000/health
    • Verify network proxy configurations if offline. The sync queue will resume automatically once connection is restored.

AI Provider Issues

OpenRouter Authorization Failures

  • Symptom: Lead scoring returns mock template fallbacks, and logs display authorization errors.
  • Solution:
    • Check your OpenRouter API key under Settings.
    • Verify that the key is valid and has sufficient credits.
    • Run pnpm test:ai in the monorepo root to verify connection health.

Ollama Model Unavailable

  • Symptom: Offline qualification runs fail with model not found.
  • Solution:
    • Verify Ollama is running:
      bash
      curl http://localhost:11434/api/tags
    • Pull the required model locally:
      bash
      ollama pull llama3.1
PREVIOUSAI Agents & RuntimesNEXT Architectural Decision Records