TryMellon

QR Default — Support Playbook

Troubleshooting guides and standardized responses for QR default domain issues.

QR Default — Support Playbook

Standardized troubleshooting and responses for support tickets related to the QR default domain feature.

Scenario 1: “The QR code doesn’t work”

Diagnostic Steps

  1. Check the QR URL

    • Scan the QR with a QR reader app (not the demo). Does the URL look like https://trymellon-landing.pages.dev/mobile-auth?session_id=...?
    • If the URL is malformed or missing session_id, the init() call may be failing. Check console errors on desktop.

  2. Verify the origin is allowed

    • The desktop app’s origin must be in Allowed origins in the dashboard.
    • Common mistake: using http://localhost:3000 (backend) instead of http://localhost:4173 (frontend).

  3. Check session TTL

    • QR sessions expire after 5 minutes. If the user waits too long, the QR becomes invalid.
    • Solution: refresh the page or call init() again to get a new QR.

  4. Check browser support

    • WebAuthn requires: Chrome ≥ 67, Safari ≥ 14, Firefox ≥ 60, Edge ≥ 79.
    • Mobile: iOS ≥ 16 (FaceID passkeys), Android ≥ 9 (FIDO2).

  5. Check network

    • Both desktop and mobile need internet access.
    • If behind a corporate proxy, WebAuthn attestation might be blocked.

Standardized Response

“Please check the following:

  1. Your desktop app’s origin is listed in Allowed origins in the TryMellon dashboard.
  2. You’re scanning the QR within 5 minutes of it appearing.
  3. Your mobile browser supports WebAuthn (Chrome, Safari, Firefox on iOS 16+ or Android 9+).
  4. Both devices have internet access.

If the issue persists, share the browser console output from the desktop and we’ll investigate further.”

Scenario 2: “Many QR sessions are expiring / high error rate”

Diagnostic Steps

  1. Check session volume vs. plan limit

    • Dashboard → Settings → Plan limits → QR sessions / month.
    • If at or near the limit, sessions may be throttled.

  2. Check polling timeout

    • The SDK’s waitForSession() has a built-in timeout (typically 2–3 minutes).
    • If users consistently take longer, the session expires before approval.

  3. Check mobile page loading time

    • If the bridge page is slow to load, users may give up before approving.
    • Test the bridge URL directly: https://trymellon-landing.pages.dev/mobile-auth?session_id=test.

  4. Check for retry storms

    • If the client calls init() repeatedly (e.g., on every render), it creates sessions that expire unused.
    • Solution: call init() once and store the result.

Metrics to Check

MetricWhere to find itMeaning
QR sessions createdDashboard → Overview → API callsTotal init() calls
QR sessions completedBackend logsSessions that reached completed status
QR sessions expiredBackend logsSessions that timed out (5 min TTL)
Completion ratecompleted / createdShould be > 60% for healthy usage

Standardized Response

“A high expiration rate usually means one of:

  1. Users aren’t scanning in time — the QR expires after 5 minutes. Consider showing a countdown or auto-refresh.
  2. Retry storms — if your code calls init() on every render, it creates sessions that expire unused. Call init() once and reuse the result.
  3. Plan limits — check Dashboard → Settings → Plan limits to see if you’re near your QR session quota.

Can you share your QR session completion rate? (completed sessions / total sessions created)“

Scenario 3: “QR default not available on my plan”

Response

“QR default domain is included in the Growth ($79/mo) and Scale ($159/mo) plans. Your current plan doesn’t include this feature.

You can upgrade from Dashboard → Settings → Billing. After upgrading, the QR default indicator in Plan Limits will show ‘Enabled.’

If you’d like to try QR login before upgrading, the cross-device flow itself works on all plans — you just need to host your own /mobile-auth page. See our Cross-Device Authentication guide.”

Scenario 4: “I want to use my own domain instead of the bridge”

Response

“You can switch to your own domain at any time:

  1. Deploy a page at https://yourdomain.com/mobile-auth that handles the approval flow (see Cross-Device docs).
  2. In the dashboard, set primary_qr_base_url to https://yourdomain.com.
  3. Add https://yourdomain.com to Allowed origins.

No user migration needed — existing passkeys continue to work.”

Escalation

If the above steps don’t resolve the issue:

  1. Collect: desktop browser console logs, mobile browser console logs, session_id (from the QR URL), timestamp.
  2. Check backend logs for the specific session_id.
  3. Escalate to engineering with all collected data.