--- url: >- https://docs.corbitaltech.dev/products/whatsapp-qr-login-for-whatsmark-saas-bundle/troubleshooting.md description: >- Solutions for the most common issues with the WhatsApp QR Login Module — QR expiry, connection failures, pending messages, voice notes, and bans. --- # 🛠️ Troubleshooting *** This page collects fixes for the issues we see most often. If your problem isn't listed, check the [FAQ](/products/whatsapp-qr-login-for-whatsmark-saas-bundle/faq.md) or contact support via your CodeCanyon item page. ## 8.1 The QR Code Expires Before I Can Scan It QR codes are valid for about **60 seconds** — this is enforced by WhatsApp itself, not the module. The fix: 1. Click **Refresh** on the connection page — a new QR appears. 2. Make sure your phone's camera is unlocked and ready **before** you click Refresh. 3. On your phone, open **WhatsApp → Settings → Linked Devices → Link a Device** ahead of time so you're already on the camera screen. ::: tip 📷 BE READY BEFORE YOU REFRESH Most expired-QR situations come from opening WhatsApp and navigating to the camera *after* clicking Refresh. Have the phone ready first. ::: ## 8.2 "Connection Failed" Right After I Scan If the page jumps from **Connecting** straight to **Failed** after a successful scan: * Make sure your phone's WhatsApp is **up to date** (open the app store and check for updates). * Try again on a **stable network** — avoid VPNs or restrictive Wi-Fi while scanning. * If the same error keeps coming up, **delete** the connection and start a fresh one. * If that still doesn't work, contact your administrator — they may need to check the gateway service is running and reachable. ## 8.3 Messages Stay on "Pending" Pending normally lasts only a second or two. If a message stays pending: * For **more than a minute**, it usually clears on its own. * For **more than 10 minutes**, the system marks it as **Failed**. You can retry by sending again. * If **every message** in every chat stays pending, your connection is most likely offline — go to the **Connection** page and check the status. Click **Reconnect** if it's not showing **Connected**. ## 8.4 The Chat List Shows Old Messages but Nothing New Arrives This usually means the WebSocket connection between your browser and the gateway has silently dropped. 1. **Refresh the page** once. 2. If new messages still don't flow, your connection may have silently dropped on the gateway side — go to the **Connection** page and click **Reconnect**. 3. If reconnecting succeeds but new messages still don't appear, ask your administrator to verify the gateway service is healthy (`/health` endpoint). ## 8.5 Voice Notes Won't Record The browser needs **microphone permission** for the page. 1. Look for a microphone icon in your address bar — click it and **allow** access for this site. 2. Reload the page so the new permission takes effect. 3. Try Chrome or Edge if recording fails in another browser — they have the most reliable WebRTC microphone support. 4. If you're on macOS, also check **System Preferences → Security & Privacy → Microphone** and make sure your browser is allowed. ## 8.6 Media Files Won't Upload If image, video, audio, or document attachments fail: * Check the **file size** — see [Limits & Quotas](/products/whatsapp-qr-login-for-whatsmark-saas-bundle/limits.md) for the caps. Files above WhatsApp's limits are silently rejected. * Check the **file type** — for example, `.heic` photos from iPhones must be converted to JPG/PNG first. * Make sure your **HTTPS certificate is valid** — browsers refuse to upload large files from pages with broken SSL. ## 8.7 My Number Got Banned If WhatsApp bans the connected number, **no third-party tool can recover it** — the ban is on WhatsApp's side. To avoid being banned in the first place: * **Don't send unsolicited messages** to people who don't know you — that's the #1 way numbers get reported as spam. * Spread sends out over the day — the built-in throttle is there for a reason; don't ask your administrator to remove it. * Make sure your message templates **feel personal**, not robotic. Use merge fields, vary the wording, don't paste the exact same message 200 times. ::: danger 🚫 NO RECOVERY FROM A FULL BAN A fully-banned number cannot be restored by the module, by Corbital, or by anyone other than Meta. Start fresh with a new SIM and warm it from day 1. Treat ban prevention as a hard requirement, not an optimisation. ::: ## 8.8 The Gateway Health Check Fails If `/health` on the gateway returns a non-`200` status or times out: 1. SSH into the gateway host and check the process is running (`pm2 status` or `systemctl status`). 2. Tail the gateway logs and look for crash traces or database connection errors. 3. Verify the database credentials in the gateway `.env` are correct and the database is reachable. 4. Restart the gateway and watch the logs for clean startup messages. ## 8.9 WebSocket Doesn't Upgrade Behind nginx / Apache If chats don't update live but sending works: * Confirm your reverse proxy is configured to forward WebSocket upgrades. For nginx, the `proxy_set_header Upgrade $http_upgrade` and `proxy_set_header Connection "upgrade"` directives are required (see the snippet in the [Installation Guide](/products/whatsapp-qr-login-for-whatsmark-saas-bundle/installation.md#reverse-proxy-websocket-hint)). * If you're behind Cloudflare, make sure the gateway endpoint isn't on a "Lite" plan that strips WebSocket upgrades. ## 8.10 Recipient Sees "Waiting for This Message. This May Take a While." This happens when a contact has messaged you using WhatsApp's newer, privacy-focused identifier (a **LID**) instead of their plain phone number. WhatsApp keeps a separate, independent encrypted session for each — so a message sent to the phone number can't always be opened by a device that's expecting the LID session, and vice versa. The module handles this automatically in most cases: * It learns the phone-number ↔ LID pairing every time a contact messages you or syncs their profile. * Once learned, it automatically sends to the correct identifier for that contact. * Sent messages are kept for **3 days** so they can be automatically resent if the recipient's device asks for them again. **What this means for you:** * The very **first** message to a brand-new contact can occasionally hit this — it clears itself as soon as that contact replies once. * If it keeps happening on an established chat, ask your administrator to confirm the gateway is running the latest version of the module. * No message is lost — it resends automatically once the pairing is known; you don't need to send it again by hand. *** *If your issue persists after all of the above, contact support via the CodeCanyon item page with: a description of what you tried, your gateway log output around the time of the issue, and the connection status as shown in the dashboard.*