MagicDX

Theme

Magic-Link — Troubleshooting ​

Emails not arriving ​

  1. Check Strapi logs for email-service errors.
  2. Check your email provider's send logs (Gmail sent folder, SendGrid Activity, etc.).
  3. If using Magic-Mail — check Magic-Mail → Email Logs.
  4. Verify routing — which account is being used? Is it rate-limited?
  5. Check spam folder — especially on first emails from a new domain.
  6. For production: set up SPF, DKIM, DMARC DNS records for the sending domain.

Token expired too quickly ​

Default expiry is 15 minutes. Increase if needed:

typescript
'magic-link': {
  config: { tokenExpiry: 60 * 60 },  // 1 hour
},

Or for specific users with slow email (corporate spam filters), set longer for them specifically in the admin UI.

"Token invalid" on every click ​

Common cause: link was scanned by an email preview service (Outlook Safe Links, McAfee GTi, etc.) which consumed the one-time token.

Fix: enable Email OTP (Premium) or browser pinning (Advanced) so pre-opens don't invalidate the flow.

Rate limited ​

429 Too Many Requests — Retry-After: 2400

Common during dev/testing when you hit /send repeatedly. Fixes:

  1. Wait the Retry-After seconds.
  2. In dev, adjust config to higher limits:
    typescript
    rateLimitPerIP: { window: 60, maxAttempts: 100 },
  3. For legitimate high-volume scenarios, implement Magic-Sessionmanager geo-fencing to whitelist trusted IPs.
  4. Unban a specific IP in admin → Magic-Link → Banned IPs.

TOTP code always rejected ​

Three causes:

  1. Clock drift — server or client clock is off by more than 30 seconds.
    • Check server NTP (timedatectl status on Linux).
    • Check client device auto-time setting.
  2. Wrong secret — user entered the secret manually and mistyped.
    • Re-enroll: disable MFA, re-enroll with QR scan.
  3. Authenticator bug — rare, but some apps have drift issues.
    • Try a different app (Authy → Google Authenticator).
    • Use a backup code as workaround.

"User not found" on verify ​

Happens when autoCreateUsers: false and the email has no matching user. Either:

  • Enable auto-creation: autoCreateUsers: true.
  • Create users manually in admin → Users.
  • Pre-register via the Users & Permissions API.

JWT validation fails ​

After login, your API rejects the Magic-Link JWT. Check:

  1. Same JWT_SECRET across all Strapi instances (if load-balanced).
  2. JWT is passed in Authorization: Bearer ... header.
  3. Token has not expired — default Strapi JWT lifetime is 30 days.
  4. User is not disabled — check user record blocked: false.
bash
rm -rf .cache dist node_modules/.cache
npm run build
npm run develop

Check:

  • 'magic-link': { enabled: true } in config/plugins.ts.
  • Logged-in admin user has permission to see the plugin (default: Super Admin can).

Enable debug mode ​

bash
DEBUG=magic-link:* npm run develop

Logs every token generation, validation attempt, rate-limit check, and email send trigger.

Still stuck? ​