Why Wi-Fi QR codes fail to connect
Almost every failure is one of four things: escaping, an all-hex SSID, a hidden network flag, or a client that never supported the format.
What this covers
- The WIFI: payload field by field, including the double semicolon
- The escaping rules, the all-hexadecimal SSID trap, and why the password is never quoted
- A symptom-to-cause table for the common failures
- Platform support, and the networks the format simply cannot describe
What it does not
- Enterprise 802.1X provisioning, which needs a configuration profile rather than a QR code
- Router configuration advice beyond what changes whether a code works
- Any way to hide the password: it is in the printed square by design
The payload, exactly
A Wi-Fi QR code is a single line of text in a format the phone's Wi-Fi settings understand. It is not a network protocol and it is not encrypted; it is a description of a network, written down.
WIFI:T:WPA;S:Cafe Nord;P:flat white 2026;;- T is the security type: WPA for WPA2 and WPA3 networks, WEP for the obsolete kind, nopass for an open network.
- S is the SSID, exactly as broadcast, including capitals and spaces.
- P is the password. It is omitted for nopass networks.
- H:true marks a network that does not broadcast its name. There is no H:false: the field is left out entirely for an ordinary network, because a few readers treat the presence of H as the hidden flag whatever its value says.
- The line ends with a semicolon closing the last field and then a second semicolon closing the payload. That double semicolon is part of the format, not a typo.
Escaping, which is where most of them break
The characters \ ; , : and " have structural meaning in that line, so inside the SSID and the password each must be preceded by a backslash. A password of p;ssw0rd has to be written P:p\;ssw0rd, and a network named Nord, Cafe has to be written S:Nord\, Cafe. A generator that skips this produces a code that decodes cleanly and then reports an incorrect password, because the phone stopped reading the password at the semicolon.
The second trap is a value made entirely of hexadecimal digits, which is a legacy of WEP: S:12345678 can be read as a raw hex byte string rather than as those eight characters. The grammar resolves it by wrapping the value in double quotes — S:"12345678" — and the generator here does that for the SSID and for the SSID only.
A password is deliberately never quoted, and that is the more useful half of the rule. All-numeric passphrases are ordinary, so quoting on the same test would fire constantly, and a reader that failed to strip the quotes again would hand the router a passphrase with two extra characters in it. That trades a certain failure for an ambiguity only some readers have, so the password goes in escaped and unquoted.
Escaping and the SSID quoting are applied for you on this site. The reason to know the rules is diagnostic: if a code made elsewhere fails on a network whose password contains punctuation, missing escapes are almost always the cause, and if such a code wraps the password in quotes, a phone passing those quotes straight through to the router is the thing to suspect. Either way, decode the code and read the line.
Symptom to cause
| What you see | Likely cause | What fixes it |
|---|---|---|
| Incorrect password, on a password you know is right | An unescaped ; , : or backslash in the password, or a generator that wrapped the password in quotes the phone then passed to the router | Regenerate with escaping and with the password left unquoted |
| Nothing happens when the code is scanned | The reader does not handle the WIFI: format | Use the built-in camera on iOS 11 or later, or Android 10 or later; on older Android use Google Lens |
| The network never appears in the list | A hidden SSID with the hidden flag not set | Regenerate with H:true |
| It joins, then nothing loads | A captive portal waiting for a browser sign-in | Open any http page to trigger the portal, and put a note beside the code |
| Works on one phone, fails on another | A WPA3-only network with an older client, or an SSID broadcast only on 5 GHz | Enable WPA2/WPA3 transition mode, and broadcast the same SSID on 2.4 GHz |
| Worked last month, fails now | A guest network that rotates its password on a schedule | Fix the guest password, or accept reprinting the card each time it changes |
| The corporate network never joins | 802.1X credentials cannot be expressed in this format | Distribute a configuration profile instead; the QR route does not cover enterprise |
| An SSID with an emoji or an accent joins the wrong network | The SSID was typed rather than copied, or the reader assumed a different character set | Copy the SSID from the router page character for character and test on both platforms |
What the format cannot describe
WPA3 has no security type of its own in the original format. T:WPA is what current devices expect for WPA2 and for WPA2/WPA3 transition mode, and it works. A network configured as WPA3-only can still refuse an older client, and no payload can change that — it is a client capability, not a code property.
Enterprise networks are further out of reach. 802.1X needs an identity, an EAP method and usually a certificate. Android has vendor extensions covering parts of it; iOS does not accept enterprise Wi-Fi from a QR code at all. If your network authenticates each user individually, a managed configuration profile is the supported route and a printed square is not.
And the password is in the code. Anyone who photographs the card has it, permanently, and can pass it on without passing on the card. That is inherent to the format: a guest network with a password you are content to have copied is the right thing to put behind one, and the network you run your till on is not.
Testing a card before you print fifty
- Ask the phone to forget the network first, or the join you are watching proves nothing.
- Test one iPhone and one Android phone; the two platforms fail in different ways.
- Test the printed card rather than the screen, at the size and on the paper you will use.
- Test from where a guest will actually stand, which is usually further away and at a worse angle than your desk.
- Cross-check against the code your Android phone generates from its own network settings: if that one joins and yours does not, the difference is in the payload, not the network.