Why a QR code will not scan: input and image mistakes

Task and input

This guide is for people who create or read their own QR codes and get a code that will not decode, decodes to something unexpected, or cannot be processed at all. It covers the three content types the tool is designed to create (URL, Text and Wi-Fi) and reading a QR code from a local PNG or JPEG image. The behavior described here is the tool's intended design, not the result of independent device testing.

Troubleshooting is easier with known inputs you can compare against. These author-created examples are used throughout: the URL https://example.com/a?q=one%20two, the text Привет, мир! 😀, and the Wi-Fi payload WIFI:T:WPA;S:Guest Lab;P:demo-guest-2026;; for the network Guest Lab. The Wi-Fi name and password are fictional demo values, not a real network.

Worked steps

Step 1: rebuild the code from clean input. In Create, choose URL, Text or Wi-Fi, enter the content, and export the code as PNG or SVG. Encoding is handled by a pinned, locally served copy of qrcode-generator 1.4.4 (source: https://github.com/kazuhikoarase/qrcode-generator).

Step 2: for Wi-Fi, check each field. The WIFI payload format documented by ZXing, a practical interchange convention, uses T for the authentication type, S for the SSID, P for the password and H for a hidden network. A backslash, semicolon, comma, double quote or colon inside a value must be escaped with a backslash, so a semicolon in a network name is written as \;. For an open network, use nopass and leave out the password (source: https://github.com/zxing/zxing/wiki/Barcode-Contents). If a special character is left unescaped, it may split the value, and the result depends on the reader.

Step 3: read the image. In Read, upload a local PNG or JPEG and press Decode; decoding does not start automatically. Decoding uses a pinned, locally served copy of jsQR 1.4.0, which reads the image's pixel data and returns content only when it finds a code (source: https://github.com/cozmo/jsQR). By design, the image is not sent to an external upload service or paid runtime API.

Step 4: if Decode finds nothing, work through this retry checklist. (1) Decode the exported original instead of a photo or screenshot of it. (2) If you must use a photo, crop it so the whole code is visible without cutting off any edge, and retake blurry, glare-covered or strongly angled shots. (3) Upload only PNG or JPEG files; to read back an SVG export, save it as PNG first. (4) If the code itself is torn, smudged or partly covered, regenerate it from the original content instead of retrying the same image. (5) Upload only images you created or trust.

Verify the result

Decoded content is shown literally with a Copy button, and links are not opened automatically. Compare the output character by character with what you entered. For the URL example, the result should be exactly https://example.com/a?q=one%20two. URLs keep their scheme and case (source: https://github.com/zxing/zxing/wiki/Barcode-Contents), and because the content is shown literally, %20 appears as typed rather than as a space. That is expected, not an error.

For the text example, confirm that the Cyrillic letters and the emoji came back intact. For Wi-Fi, confirm that the raw payload matches exactly, including any escaped characters (the demo payload has none) and the trailing ;;. A matching payload shows that the code contains what you intended. It does not prove that a particular phone will join the network, because support for the WIFI convention varies between readers.

If a decoded link is not what you expected, do not visit it. Copy it, inspect the domain and path, and regenerate the code from content you control.

Limits and common mistakes

Scope is limited to creating URL, Text and Wi-Fi codes and decoding local images. No live device compatibility testing has been done, no scan rate is guaranteed, and this guide sets no universal file-size limit. Decoding an arbitrary photo may fail even when the code is valid.

Common mistakes: expecting content types outside URL, Text and Wi-Fi; forgetting to escape special characters in a Wi-Fi name or password; changing a URL's case or scheme and expecting the same result; testing with a photo of a screen instead of the exported file; assuming a decoded link is safe to open. A Wi-Fi QR code is not encryption: anyone who can scan it can read the network name and password.

Sources

Captured 2026-09-28; not reverified since. ZXing Barcode Contents (URL and WIFI conventions): https://github.com/zxing/zxing/wiki/Barcode-Contents. qrcode-generator upstream: https://github.com/kazuhikoarase/qrcode-generator; pinned release 1.4.4: https://registry.npmjs.org/qrcode-generator/1.4.4. jsQR upstream: https://github.com/cozmo/jsQR; pinned release 1.4.0: https://registry.npmjs.org/jsqr/1.4.0.