🆘 Troubleshooting & Support
Find solutions to common problems and answers to frequently asked questions.
Quick Links
| Problem | Solution |
|---|---|
| Server won’t start | See FAQ: Installation & Setup |
| MongoDB connection fails | See FAQ: Database Issues |
| WhatsApp disconnects | See FAQ: Connection & Session |
| Messages not sending | See FAQ: Messaging Issues |
| Port already in use | See FAQ: Common Errors |
| Webhook not triggering | See FAQ: Webhooks & Integration |
| Media upload fails | See FAQ: Media & Files |
| High CPU/Memory usage | See FAQ: Performance & Optimization |
Getting Help
1. Check the FAQ
- Browse Frequently Asked Questions for your specific issue
- Most common problems have quick solutions
2. Review Deployment Guide
- See Deployment Guide for environment-specific setup
- Covers VPS, Docker, Heroku, AWS, and home server deployments
3. Check API Reference
- See API Reference for endpoint specifications
- Verify request/response formats
4. Review Logs
- Check application logs:
npm run devorpm2 logs - Check MongoDB connection logs
- Enable debug mode:
DEBUG=* npm run dev
5. Search Issues
- GitHub Issues - Search existing issues
- GitHub Discussions - Ask the community
Common Issues at a Glance
Installation Issues
- npm ci fails → Check Node.js version (18+), npm cache, internet connection
- MongoDB URL error → Verify
MONGO_URLin.envfile - Port 3000 in use → Change
PORTin.envor kill existing process
Runtime Issues
- WhatsApp QR won’t scan → Check browser console, session storage, network
- Messages fail silently → Verify account is connected, check webhook logs
- API returns 404 → Verify endpoint path, account ID, and request method
- Webhook not firing → Check webhook URL is publicly accessible, no auth required
Production Issues
- High memory usage → Implement session cleanup, reduce payload sizes
- Accounts disconnect periodically → Add auto-reconnect logic, check network stability
- Database growing too large → Implement message/log cleanup policies
Debug Mode
Enable detailed logging:
# Show all debug output
DEBUG=* npm run dev
# Show only app debug
DEBUG=app:* npm run dev
# Show Socket.io events
DEBUG=socket.io:* npm run dev
# Show MongoDB queries
DEBUG=mongodb:* npm run dev
Still Stuck?
- Search GitHub Issues: notoriousarnav/wildcat/issues
- Ask on Discussions: notoriousarnav/wildcat/discussions
- Check Community: Look for similar problems in closed issues
- File a New Issue: Provide error logs, OS, Node version, and steps to reproduce
See Also
- Getting Started Guide - Installation and quickstart
- API Reference - All available endpoints
- Deployment Guide - Production setup
- Integration Examples - Real-world workflows