WiFi QR codes for guests: what actually breaks

A WiFi QR code is a plain-text line in a fixed shape: WIFI:T:WPA;S:network;P:password;;. Phones read it, join the network, and never show the password. When a guest code fails it is almost always one of three things — a character that was not escaped, a security type the phone does not expect, or a network that needs a browser step the code cannot perform.

This guide covers those three, in the order they actually bite, and ends with a test routine worth running before you print two hundred table tents.

The payload, field by field

The de-facto format — implemented by Android, iOS, most third-party scanners and every access-point vendor's guest-card generator — is a single URI-like string terminated by a double semicolon:

WIFI:T:WPA;S:My Cafe\; guest;P:p@ss\,word;;

The fields are:

FieldMeaningNotes
TAuthentication typeWPA covers WPA, WPA2 and WPA3 in practice; WEP for legacy; nopass for open networks
SSSID — the network nameCase-sensitive, exactly as broadcast, spaces included
PPasswordOmitted entirely when T:nopass
HHidden networkH:true only; leave the field out otherwise

Anything outside this shape — a username field, a domain for 802.1X, a realm — has no defined meaning in the format. Enterprise networks with per-user logins are not covered here, and no amount of clever encoding will make a consumer phone negotiate them from a QR scan.

Escaping: the bug you cannot see on screen

Five characters have structural meaning inside the payload: backslash, semicolon, comma, colon and double quote. If a network name contains one of them raw, the scanner splits the string at the wrong place. The result is a code that looks perfect, scans instantly, and then reports "network not found".

Consider a café whose guest network is literally named My Cafe; guest and whose password is p@ss,word.

Wrong: WIFI:T:WPA;S:My Cafe; guest;P:p@ss,word;;
Right: WIFI:T:WPA;S:My Cafe\; guest;P:p@ss\,word;;

In the wrong version the scanner reads the SSID as My Cafe, then treats guest as a malformed field and gives up — or worse, joins a different network with a similar name. The comma in the password has the same effect: it terminates the field early, so the phone tries to authenticate with p@ss.

This generator escapes those five characters for you and prints the exact payload under the preview, so you can see the backslashes before you print. If you are writing the string by hand in a spreadsheet or an access-point config, escape backslash first, then the others — otherwise you end up double-escaping your own escape characters.

The same rule applies to emoji and accented letters in an SSID. They are fine, but only if the encoder writes UTF-8 bytes; a Latin-1 encoder turns Café into something the phone cannot match to the broadcast name.

WPA3, and why the field still says WPA

The WIFI: format was defined before WPA3 existed, and the T field has only three widely supported values. In practice phones treat T:WPA as "WPA-family, try the modern handshake" and will join a WPA3-only network from a code that says WPA. What they will not do is join a network whose security mode does not match what the code claims.

The realistic failure is a mixed-mode access point set to WPA2/WPA3 transition while the code says WEP, or a legacy device on the guest network forcing WPA-TKIP while modern phones refuse it. Check the access point's actual security mode before generating, and if the network is WPA3-only and old phones must join, that is a configuration decision rather than a QR decision.

Hidden networks: H:true is a hint, not a guarantee

If the SSID is not broadcast, add H:true. Some phones then attempt a directed probe with the name from the code; others require the network to appear in a scan and simply fail. iOS in particular is inconsistent across versions, and Android behaviour varies by OEM skin.

If guests must use a hidden network, test on the actual devices your guests carry. Better: stop hiding the SSID. Broadcast names are not a security control — the name is visible to anyone who connects — and hiding it costs you a working QR code plus a measurable amount of battery life on client devices.

Captive portals: the step the code cannot do

Hotels, cafés and airports often run a portal: you join the WiFi, then a browser page asks for a room number, an email address or a voucher code. A QR code gets the phone onto the network and stops there. The guest still faces the portal.

That is not a bug, but it does make "scan to get online" a misleading instruction. Say "scan to join the WiFi, then sign in on the page that opens" instead. If the phone does not open the portal automatically, the guest has to visit a plain-HTTP address to trigger it — worth printing next to the code.

There is a second-order problem here: portal networks frequently isolate clients from each other, so a guest who scans and joins cannot reach a Chromecast, a printer or another guest's laptop. If your venue depends on that, the guest VLAN configuration matters more than the code.

Passwords that rotate, and codes that do not

A static WiFi code carries the current password. Rotate it monthly and every printed card is wrong. Two workable patterns:

  • Long-lived guest password. One password, changed quarterly, with cards reprinted on the same schedule. Simple, predictable, no dependency.
  • Portal with vouchers. The code only joins the network; the password is stable and the real access control lives in the portal. Rotating vouchers does not require reprinting the code.

What does not work is pretending a static code is dynamic. If you need the password to change without reprinting, you need a redirect service or a portal — with the dependency that implies, as described in the static versus dynamic comparison.

Print and placement

A WiFi code is scanned at close range, usually by someone already sitting at your table, so it can be small — but not arbitrarily small. Below roughly 15 mm across, phone cameras start struggling with autofocus at that distance, and the four-module quiet zone gets cropped by the artwork. The maths for that is in the print size guide.

Two placement mistakes show up constantly: printing dark modules on a dark brand colour, and putting the code over a photograph. Both destroy the contrast between modules and background, which is what the scanner actually measures. Keep a clear white margin around the symbol even if the card's background is coloured, and never let a laminate reflection sit between the code and the camera lens.

A test routine worth the five minutes

  1. Generate the code with the real SSID and password, including any punctuation.
  2. Scan it on at least one iPhone and one Android phone, using both the built-in camera and a third-party scanner.
  3. Confirm the phone joins the network, not just that it displays the name.
  4. Print one copy on the actual material — card, laminate, sticker — and scan it under the lighting where it will live.
  5. Ask someone who has never seen the code to scan it without instructions. If they need help, the label is the problem.

Frequently asked questions

Does the code work on iPhones?

Yes. iOS 11 and later read the WIFI: format in the Camera app and offer to join. Older versions and some third-party scanners do not, which is one more reason to test on a real device rather than an emulator.

How do I encode an open network?

Use T:nopass and leave the P field out entirely — an empty P: is not the same thing and some scanners treat it as a password of zero characters. The generator's "Open" option does this for you.

Why does the phone join but show no internet?

The network is up but the uplink is not, or the portal has not been completed. A QR code has no influence on either; it only supplies the credentials. Check the access point's WAN status and the portal configuration.

Generate a WiFi code with automatic escaping and a payload readout you can verify by eye before printing.

Written by the QRQuick team. Last updated November 19, 2026.