[META] QR Code / Pairing issues — tracking umbrella

Meta-issue consolidating all open QR Code / pairing-related reports. Please do not open new QR Code issues — comment here instead.

Known symptoms

• QR Code never appears, loading forever (/instance/connect returns {"count": 0})
• QR Code is generated but invalid / expires immediately
• Connects then drops: stream errored out (code 515) + Pre-key upload timeout (code 408)
• Android devices cannot read QR while iOS can
• Pairing code login succeeds but no message events received (401 / device_removed)
• QR refreshes every 1 minute instead of WhatsApp's native 3 minutes
• Endpoint /instance/qrcode returns 404 (v2.3.1)
• Behind Cloudflare / nginx: 504 Gateway Timeout generating QR
• Behind Coolify / Railway / Docker: QR not generated

Known working workaround (community-sourced, see #2463 for full walkthrough)

Set the following env vars and restart the container:

CACHE_REDIS_ENABLED=false
CACHE_LOCAL_ENABLED=true
DATABASE_SAVE_DATA_CHATS=false
DATABASE_SAVE_DATA_CONTACTS=false
DATABASE_SAVE_DATA_HISTORIC=false
DATABASE_SAVE_DATA_LABELS=false
CONFIG_SESSION_PHONE_VERSION=2.3000.1033773198

Root cause (per community analysis): the server chokes on CPU/RAM when Baileys generates pre-keys at the same time that the Meta history "tsunami" arrives, causing pre-key timeout → stream error 515 → device kick. Redis over Docker network adds latency; disabling history sync and switching to local cache removes the bottleneck.

Scope

This umbrella tracks the infrastructure-level QR/pairing problem. Sub-topics that deserve their own issue:

• Chatwoot-specific QR regeneration bugs → see #2014 (Chatwoot umbrella)
• @lid vs @jid in pairing flow → see @lid umbrella

For maintainers

All duplicate QR Code issues are being closed with state_reason: duplicate pointing here. If you want to respond per-user, use this thread as the single source of truth.

This issue was reorganized from the original report ("Não gera QR Code da Instancia") as part of the 2026-04 issue triage. The original reporter (@jpedrodouradoo-cell) and all community contributors remain credited in the comment history.