Troubleshooting

Work top-down: most production issues are one of the first three.

First checks, always

pm2 status                    # whatsmax-web and whatsmax-worker both online?
pm2 logs whatsmax-web --lines 100
pm2 logs whatsmax-worker --lines 100
crontab -l | grep scheduler   # is the scheduler cron entry there?
redis-cli ping                # PONG?
mysql -u whatsmax -p -e "SELECT 1"

And in the admin panel: System → Queue (is work draining?) and System → Cron Setup (is the scheduler heartbeat recent?).

Nothing background works (campaigns queued, bots silent, posts not publishing)

Cause: the worker is not running, the scheduler cron entry is missing, or Redis is unreachable.

• pm2 status — restart anything not online: pm2 restart whatsmax-worker.
• crontab -l — the line * * * * * cd /var/www/whatsmax && node scripts/scheduler ... must be there. Admin → System → Cron Setup shows the exact line for your install.
• redis-cli ping — if no PONG, fix Redis or REDIS_URL.
• Check pm2 logs whatsmax-worker for connection errors.
• Look at Admin → System → Queue for failed jobs and their error messages, and retry them from there.

Login loops back to the login page

Cause: auth URL mismatch behind the proxy.

• NEXTAUTH_URL and APP_URL must exactly equal the public URL (scheme included).
• AUTH_TRUST_HOST=true must be set.
• Nginx must forward Host and X-Forwarded-Proto headers (config).
• Restart the web process after fixing.

Webhooks fail to verify (Meta / gateways)

• The URL must be public HTTPS with a valid certificate — test it with curl -I https://your-domain/... from outside the server.
• Copy the callback URL and verify token exactly as displayed in WhatsMax.
• Confirm Nginx isn't blocking or buffering /api/webhooks/*.

npm run build fails

• Out-of-memory on small servers is the usual cause — add swap:

sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile
sudo mkswap /swapfile && sudo swapon /swapfile

• Node version too old — needs 20+ (node --version).
• After updates, always npm install before npm run build.

Database errors on start (P1001, access denied, unknown database)

• DATABASE_URL credentials/host/port wrong — test with the same values via mysql -u ... -p -h 127.0.0.1 whatsmax.
• Special characters in the password must be URL-encoded (@ → %40, # → %23).
• Migrations not applied — run npm run db:deploy.

Prisma client errors (@prisma/client did not initialize)

npm run db:generate && npm run build && pm2 restart whatsmax-web

Media uploads fail

• Local storage: the app user needs write permission to public/storage; Nginx client_max_body_size must allow the file size.
• S3: verify bucket, region, credentials and (for S3-compatibles) AWS_ENDPOINT.

Realtime not updating

See the dedicated table in Realtime → Troubleshooting. Short version: rebuild after setting NEXT_PUBLIC_* vars, match clusters, add WebSocket headers in Nginx.

Emails not arriving

• MAIL_TRANSPORT still log? Switch to smtp with real credentials and restart.
• Test credentials with your provider's own tooling; check spam and SPF/DKIM alignment for the From domain.

Where the logs are

Still stuck?

Contact support via your purchase page with: your server OS, Node version (node --version), what you did, the exact error, and relevant log excerpts. Screenshots of Admin → System → Queue and Cron Setup help a lot.