纠错失败时：调试无法读取的QR Codes
Systematic troubleshooting for QR codes that won't scan: contrast, quiet zone, size, encoding errors, and corruption.
When Error Correction Fails: Debugging Unreadable QR Codes
When a QR code will not scan, systematic troubleshooting identifies the root cause faster than guessing. This guide walks through the most common failure modes and their fixes.
Systematic Debugging Checklist
Step 1: Verify the Data - Is the encoded data correct? Regenerate and test a fresh QR code on screen. - If the fresh code scans, the issue is physical (print, placement, or environment).
Step 2: Check the Quiet Zone - Is there at least a 4-module-wide white margin on all sides? - Are graphics, text, or borders encroaching on the quiet zone? - This is the #1 cause of scan failure in design-heavy applications.
Step 3: Measure Contrast - Hold the printed code under good lighting and check visually. - Dark modules should be clearly darker than light modules. - Coloured QR codes must maintain sufficient contrast ratio.
Step 4: Check Physical Size - Is each module at least 0.33mm (for close-range scanning)? - At the expected scan distance, are modules large enough to resolve? - Use the sizing guide formula: QR size >= distance / 10.
Step 5: Test the Environment - Is lighting adequate? Low-light scanning requires larger codes. - Is there glare on the surface? Glossy lamination causes reflections. - Is the code on a curved surface? Geometric distortion may exceed correction.
Step 6: Test Multiple Scanners - If one scanner fails but another succeeds, it is a scanner sensitivity issue. - iOS native camera, Google Lens, and dedicated apps have different tolerances.
Common Failure Modes
| Symptom | Likely Cause | Fix |
|---|---|---|
| Never scans | Quiet zone violation | Add 4-module margin |
| Scans intermittently | Low contrast or small size | Increase size or contrast |
| Scans close but not far | Modules too small for distance | Increase print size |
| Scans on some phones only | Scanner app differences | Test on more devices, increase EC level |
| Was working, now fails | Physical damage or fading | Reprint with higher EC level |
Prevention
- Always test before mass printing
- Use EC Level M minimum for print applications
- Maintain contrast ratio above 40% (ideally above 60%)
- Follow the deployment checklist
Key Takeaways
- Debug systematically: data, quiet zone, contrast, size, environment, scanner
- Quiet zone violations are the most common cause of scan failure
- Insufficient contrast is the second most common cause
- Multiple scanner testing reveals scanner-specific vs code-specific issues
- Prevention through testing is cheaper than debugging deployed codes