The code is on the table tent. The camera picks it up instantly, a banner drops down offering to join Cafe_Guest, you tap it, the phone thinks for four seconds and returns you to the same list of networks. No error. No explanation. Nothing.
This is a narrower problem than a code that will not scan. The scan worked. Something about the join failed. The general QR code not working hub covers the reasons codes fail to read at all, damage, contrast, size, lighting, and it covers them thoroughly. What follows is only the WiFi-specific layer that sits after a successful read.
Diagnose in this order
Work down the list. Each step rules out a chunk of causes and takes under a minute.
- Decode the code and read the raw text. A QR code scanner that shows decoded content tells you the network name, the security type, and the password the code is actually carrying, which is often not what you believe you put in.
- Join the network manually by typing the password. If manual entry also fails, the password is wrong and the code is innocent.
- Forget the network on the test phone, then scan again.
- Test on a second phone, ideally a different platform.
- Check what kind of network it really is, because some kinds cannot be joined by a password code at all.
Most failures resolve at step one or two. Steps three through five exist for the ones that do not.
The security type in the code does not match the network
A WiFi QR code carries an encryption field alongside the name and password. Set it to the wrong value and phones handle the mismatch inconsistently. Some correct for it silently. Some fail without a message.
The common cases:
- The code says WPA and the network is actually open with no password, so the phone tries to authenticate against something that is not asking for authentication.
- The code says open and the network wants a password, so the phone joins with no credentials and gets rejected.
- The code says WEP because somebody picked the first option in a dropdown. WEP is a different, much older scheme and is not interchangeable with WPA2.
WPA3 deserves its own note. Networks running WPA3 use a different handshake than WPA2, and while many generators encode both under the same WPA value, some devices want an explicit WPA3 marker. If your access point is set to WPA3-only rather than a mixed WPA2/WPA3 mode, older phones and laptops may be unable to join the network at all, by any method. That is a device compatibility limit, not a QR problem, and switching the access point to mixed mode usually clears it.
The password contains characters that were not escaped
The encoded string uses punctuation as structure. A WiFi code is essentially one line of text with fields separated by semicolons and colons, and a backslash marks a character that should be read literally instead of as structure.
So a password containing a semicolon, colon, comma, backslash, or quotation mark has to be escaped when the code is generated. If it is not, the decoder reads the password as ending early. The code scans, the phone receives a truncated password, the join fails.
How to catch it: decode the code and compare the password character for character against what you typed. If it is shorter, or ends right before a punctuation mark, you found the cause.
Spaces cause the same failure more quietly. A trailing space pasted in from a document is invisible in the input field and fully encoded in the finished code. Retype the password by hand instead of pasting it, then regenerate with the WiFi QR code generator.
The network name is not what you think it is
SSIDs are case sensitive and exact. Cafe_Guest and cafe_guest are two different networks as far as the phone is concerned, and a code carrying the wrong casing points at a network that does not exist. The phone usually fails quietly rather than telling you there is no such network.
Three specific traps.
Band naming. Many routers broadcast 2.4GHz and 5GHz under the same name and let the phone choose, which is fine. Others split them into two names with a suffix. If your code carries the 5GHz name and the guest is standing three rooms away where only 2.4GHz reaches, the join fails on range while looking like a code problem.
Emoji and non-Latin characters. An SSID containing an emoji or characters outside the Latin alphabet is permitted, and encoding it is legal, but device handling varies. Some phones join fine, others do not. If the code works on one platform and not the other, this is a candidate, and the same pattern of platform-split behavior shows up in QR code scans on iPhone but not Android.
Hidden networks. A network that does not broadcast its name needs an extra flag set inside the code telling the phone to look for it anyway. Not every generator exposes that option. Without the flag, the phone searches the visible networks, finds nothing matching, and gives up. If the network is hidden, either set the hidden flag or turn broadcasting back on, which for a guest network is usually the simpler choice, since hiding an SSID provides very little practical protection.
Networks a password code cannot express
Two categories will never work with a standard WiFi QR code, no matter how carefully you build it.
Captive portals. Airports, hotels, coffee chains, and many public venues put an open network in front of a login page. The join itself succeeds. Access requires accepting terms or entering a room number in a browser afterward. A WiFi QR code can carry credentials but cannot complete a web form. If your network uses a portal, the useful code is one that links to the portal page, not one that encodes a password. A portal also breaks the assumption that scanning puts somebody online instantly, which connects to the broader question of whether QR codes work without internet.
Enterprise networks using 802.1X. Corporate WPA-Enterprise setups authenticate each user individually with a username, an EAP method, and often a certificate. The standard WiFi QR format has no fields for any of that. Some platforms have shipped extensions; none of them work reliably across devices. Enterprise access needs a provisioning profile or an MDM push, not a QR code.
The phone already has a stale profile for this network
This one produces the most frustrating version of the symptom, because everything about the code is correct.
If a phone previously connected to this SSID under an old password, it holds a saved profile. Scanning a code with the new password often does not overwrite it. The phone tries the saved credentials, fails, and may then sit in a retry loop or throw a generic authentication error. Guests returning to a venue after a password change hit this constantly, and so do you when testing, since your own phone is usually the one with the longest history on that network.
The fix is to forget the network in the phone's WiFi settings and scan again. Do that before concluding a code is broken. When testing a new code, either test on a device that has never joined the network or forget it first, or you will spend an hour debugging a problem that does not exist for anybody else.
If the code still fails after all of that, decode it one more time and read the output aloud against the router's actual wireless settings. The mismatch is nearly always visible the moment both are in front of you, and the field-by-field reference is in the complete guide to WiFi QR codes.
