Supabase "Email link is invalid or has expired" (otp_expired): why the link fails and how to fix it

Nothing on this page. CheckoutAlarm doesn't see Supabase Auth emails, and it never sees your Auth errors.

It doesn't sign up, log in, read inboxes or click links. It loads one page you pick and reads Stripe with a read-only key, so it can't tell you that sign-in links are failing.

Free: 1 site, checked once a day. Pro: $19 a month, up to 3 sites checked hourly. You prove you own the site first. For Stripe we only take a restricted key with read access to Events, Webhook Endpoints and Charges. Full secret keys are refused. Compare plans

Supabase describes otp_expired as: “OTP code for this sign-in has expired. Ask the user to sign in again.” Supabase: Auth error codes

When sign-in fails, Supabase still sends the user to your redirect URL, and “the error details will be returned as query fragments in the URL”: the part after #, with error_code and error_description. Read them from window.location.hash and show the user a clear message. Supabase: redirect URLs, error handling

Supabase suggests matching the 403 errors on the verification endpoint in your API logs with otp_expired entries in your Auth logs. It flags “rapid 403 errors or otp_expired messages shortly after an email is sent” as the sign of email prefetching (part 03, step 3). Supabase: OTP verification failures

“Magic Links only work with email addresses and are one-time use only.” Supabase: passwordless email sign-in A second click, or a click on a forwarded email after the first one, finds the link already spent. Supabase's advice for reset emails is to tell users not to forward them and to click the link directly. Supabase: OTP verification failures

By default, magic links and email OTPs expire after 1 hour. The Email OTP expiration setting also covers confirmation, password recovery, email change and invite links. Supabase: passwordless email sign-in A user who opens yesterday's email gets this error.

“Certain email providers may have spam detection or other security features that prefetch URL links from incoming emails.” Supabase names Safe Links in Microsoft Defender for Office 365 as an example. The {{ .ConfirmationURL }} is then consumed instantly, and the real user gets an expired or invalid token error. Supabase: email prefetching The troubleshooting article puts it this way: a scanner “can consume the OTP token by accessing the link before the legitimate user does.” Supabase: OTP verification failures

With the PKCE flow, the code verifier is “created and stored locally when the Auth flow is first initiated.” So “the code exchange must be initiated on the same browser and device where the flow was started.” The auth code is valid for 5 minutes and can only be exchanged once. Supabase: PKCE flow A user who asks for the link on a laptop and opens it on a phone breaks this rule.

If more than one PKCE flow is started in the same browser before either one completes, the later flow overwrites the stored code verifier, and exchanging the first flow's code fails. Supabase: PKCE flow Related codes: flow_state_expired (“Ask the user to sign in again”) and flow_state_not_found, which retried requests can cause. Supabase: Auth error codes

Supabase also lists a gap between the user's device clock and the server's time as a less common cause of tokens appearing invalid. Supabase: OTP verification failures

The quick fix for one user is the one in the error code: ask them to sign in again. Supabase: Auth error codes By default they can request a new magic link once every 60 seconds. Supabase: passwordless email sign-in Out of emails? See Supabase email rate limit exceeded.

{{ .Token }} holds a 6-digit one-time password that can be used instead of the confirmation URL. Put it in the email template, link the user to a page where they enter their email and the code, then call supabase.auth.verifyOtp({ email, token, type: 'email' }). Supabase: email prefetching, option 1 The troubleshooting article gives the same advice: the link should only take the user to a page to enter the OTP. Supabase: OTP verification failures

Supabase's second option: link to a page of your own with a button, and put the real confirmation link in the button, for example {{ .SiteURL }}/confirm-signup?confirmation_url={{ .ConfirmationURL }}. Supabase: email prefetching, option 2 Your email provider may also offer its own ways to stop prefetching. Supabase: OTP verification failures

For PKCE, Supabase edits the Magic Link template to send a token hash to your own endpoint: {{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=email. At /auth/confirm you call verifyOtp({ token_hash, type: 'email' }) to get the session. Supabase: passwordless email sign-in

Go to Authentication, then Sign In / Providers, then Auth Providers, then Email, and set Email OTP expiration. Supabase says more than 86,400 seconds (one day) is strongly discouraged and can only be set with the Management API. Supabase: passwordless email sign-in

If your external email provider enables “email tracking”, Supabase warns that the links in its email templates are overwritten and won't work as expected. Supabase: email tracking

If the link opens localhost:3000 or the wrong page, that's a Site URL or Redirect URLs setting: Supabase magic link redirects to localhost. If no email arrives at all: Supabase confirmation email not arriving.