HubNest Docs

Troubleshooting

Resolution guides for common deployment, runtime, authentication, and integration errors.

Common Issues & Resolutions

1. OTP Verification / SMS Dispatch Failures

  • Symptom: Verification SMS code is not delivered or Twilio logs an API gateway error.
  • Resolution:
    1. Check your .env parameters inside the backend folder. Ensure Twilio keys (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN) are active.
    2. If Twilio's balance is low or rate limits are hit, check if the system successfully falls back to Resend / SMTP email verification.

2. database migration lock errors

  • Symptom: Node backend crashes with lock violation error during migrations.
  • Resolution:
    • Run the SQL recovery command targeting the Knex lock table to release active migration locks:
    UPDATE knex_migrations_lock SET is_locked = 0;

3. Hydration Mismatch Warnings in Browser

  • Symptom: Browser console logs hydration mismatches when loading docs or layouts.
  • Resolution:
    • Verify that the suppressHydrationWarning attribute is defined on the root <html> tag inside app/layout.tsx.
    • Ensure theme-dependent elements (like ThemeToggle) only render icons and values after checking the React mounted lifecycle hook.

4. Redis connection exceptions

  • Symptom: Express API backend prints Redis connection failed and tasks queue crashes.
  • Resolution:
    • Check if the Redis docker service is active (docker ps). If needed, restart the container:
    docker restart hubnest-redis

Database Schema

Comprehensive specifications of core PostgreSQL tables, indexes, entity relations, and migrations.

Changelog

Keep track of version updates, feature additions, and security improvements in HubNest CRM.

On this page

Common Issues & Resolutions1. OTP Verification / SMS Dispatch Failures2. database migration lock errors3. Hydration Mismatch Warnings in Browser4. Redis connection exceptions