What if the QR code expires too fast to scan?

WhatsApp QR codes are only valid for about 60 seconds by design. Have WhatsApp already open on your phone with the camera or Linked Devices scanner ready before you generate the code, rather than opening the app after the QR appears — that alone fixes most "it expired before I scanned it" cases.

Do I need to reinstall the gateway to fix a QR problem?

Almost never. Reinstalling is Fix 6 territory, and only after reload, gateway status, linked devices, and an update haven't solved it. Most QR problems are session or network issues, not a broken install.

Could a firewall be blocking the QR code from loading?

Yes, especially on VPS gateways or restrictive office networks. WhatsApp pairing needs an open outbound WebSocket connection; if that's blocked, the QR box stays blank with no error message. Try a different network to confirm before digging into firewall rules.

How long should generating and scanning a QR code normally take?

From clicking to a confirmed connection should take under 30 seconds on a working setup: the QR renders almost instantly, and scanning it connects within a few seconds. If it's consistently slower than that, something in Fixes 2-6 is worth checking even if it eventually connects.

WhatsApp QR Not Loading? 6 Fixes - WaSMS Learn

You open the Channels page, expect a QR code, and get a blank box or a spinner that never resolves. WhatsApp QR not loading almost always comes down to one of six causes, and in order of how often each one is the actual problem, here's what to check first.

Why WhatsApp QR not loading happens

Before the fixes: the QR code your gateway shows is generated fresh each time, using a short pairing session between your browser, WaSMS, and WhatsApp's servers. When any link in that chain is stale, offline, or blocked, the QR box stays blank or spins forever instead of showing a clear error — which is why "not loading" covers such a wide range of underlying causes.

Fix 1: reload the page

Start here before anything else. The QR code is generated by a short-lived session between your browser and the gateway, and that session occasionally times out silently without showing an error. A hard reload (not just clicking back) regenerates the request from scratch.

Windows/Linux: Ctrl+Shift+R
Mac: Cmd+Shift+R

![WaSMS Channels page showing the QR refresh control](IMAGE_NEEDED:screenshot of the WaSMS Channels page with the refresh button highlighted)

If the QR appears after a reload, that's the whole fix — no gateway issue at all. This solves the majority of "blank QR" reports.

Fix 2: check gateway status

If reloading doesn't help, the QR can't render because there's nothing generating it. Open the Channels page in your WaSMS dashboard and look at the gateway status badge next to your WhatsApp number.

Green / Connected — the gateway is fine, the QR issue is elsewhere (skip to Fix 3)
Red / Offline — your gateway process isn't running or can't reach WaSMS

If it's offline, the full recovery checklist is in Gateway offline: fast fixes. A QR code can only ever be generated by a gateway that's actually up.

Fix 3: clear WhatsApp Web sessions

WhatsApp allows a limited number of linked devices per number. If your number is already near that limit — old sessions from a previous gateway setup, a test connection nobody closed — new QR generation can fail silently.

On the phone that owns the WhatsApp number:

Open WhatsApp → Settings → Linked Devices
Remove any device you don't recognize or no longer use
Try generating the QR again in WaSMS

If you recently rebuilt or reinstalled your gateway, the old linked-device entry is often still sitting there. Clearing it out is the single most overlooked fix.

Fix 4: update the gateway

An outdated gateway version sometimes falls out of sync with WhatsApp's own protocol changes, which shows up as a QR that never renders rather than a clear error message. Check your gateway version against the latest release notes and update if you're behind.

# on the machine running your gateway
cd wasms-gateway
git pull
npm install
pm2 restart wasms-gateway

(Exact commands vary depending on whether you installed on a local PC or a VPS — see connecting WhatsApp with a local gateway or connecting WhatsApp with a VPS gateway for the setup that matches yours.)

Fix 5: restart the phone

If the QR loads fine but scanning it does nothing, or the phone's camera app hangs on the scan, the phone side is usually the problem, not WaSMS. A full restart clears whatever background state is stuck.

This is also the point to confirm the phone has an active internet connection — WiFi or mobile data — since pairing requires the phone to reach out, not just the browser.

Fix 6: change network

Some corporate and school networks block the WebSocket connections WhatsApp pairing relies on. If none of the above worked, try:

Switching your gateway machine to a different network
Testing on mobile data instead of WiFi for the phone doing the scanning
Checking with your network admin whether outbound WebSocket traffic is restricted

If you're running the gateway on a VPS behind a firewall, also confirm the required ports are open — a closed port produces exactly this symptom.

WhatsApp QR Not Loading: 6 Fixes That Actually Work