A user cannot reset their password
This page helps you when a user who forgot their password can’t set a new one.
Find your case by what the user sees.
There’s no “Forgot password?” link
Section titled “There’s no “Forgot password?” link”The sign-in page shows Forgot password? only when email is set up. Turn on SMTP enabled under Admin, Email - SMTP, add your SMTP server, and send yourself a test message from the Send test email tab.
The reset email never arrives
Section titled “The reset email never arrives”After the user sends the form, they always see the same message, whether or not an email went out:
If you’re a registered user, a password reset link has been sent to your email address. Make sure to search both your inbox and spam/junk folder for the link.
That’s on purpose: a different answer would tell anyone which addresses have an account. The reason stays in the audit log, as the outcome of the requested_password_reset event:
outcome |
Why no email was sent | Fix it |
|---|---|---|
unknown_address |
No user has that email address. | Check the address the user typed. They may have signed up with another. |
unverified_address |
The user’s email address isn’t verified, so the auth server won’t trust it with a reset link. | Mark it verified on the user’s Email tab, with Email verified, or set their password yourself. |
account_disabled |
The user is disabled. | Enable the user on their Details tab, if they should be able to sign in. |
code_issued |
The link was made and the email was sent, or the sending failed. | If the user still has nothing, check the auth server’s log for unable to send the password reset email, and your SMTP settings. Then check their spam folder. |
When sending fails, the auth server’s log has an error such as unable to send the password reset email, with the cause. A form sent while the auth server is very busy can be dropped, with the warning a job to run after its response was dropped, too many in flight.
An address can ask for 5 links every 5 minutes, whether or not the rate limiter is on, and with it on an IP address can ask for 20. Past that the form answers “Too many attempts”: see Too many attempts or 429.
The link says the code is invalid or expired
Section titled “The link says the code is invalid or expired”The user follows the link and sees:
Unable to set the password. The verification code appears to be invalid or expired. Please click this link and attempt the verification process again.
A reset link works once, for 5 minutes after it was sent, and the user then has 5 more minutes to fill in the form. A link to an account with no password yet, such as the one an administrator’s setup email sends, works for 24 hours instead. It stops working when:
- it’s past that lifetime;
- it was already used;
- the user asked for another one since, which replaces it;
- the user was disabled in the meantime;
- the user’s email address was changed since it was sent, by the user or by an administrator.
The user should ask for a new link and use it straight away. The reason of the failed_reset_password_code audit event narrows it down: code_expired for a link past its lifetime, marker_expired for a form sent more than 5 minutes after the link was followed, account_disabled for a disabled user, and unknown_code for a link that was used, replaced by a newer one, or retired by an address change, which it can’t tell apart.
The new password is refused
Section titled “The new password is refused”The form says why, such as “The minimum length for the password is 8 characters” or “As per our policy, an uppercase character is required in the password.” Password policy under Admin, General decides what’s needed:
| Policy | At least | Also needs |
|---|---|---|
| No policy | 1 character | Nothing |
| Low strength | 6 characters | Nothing |
| Medium strength | 8 characters | A lowercase letter, an uppercase letter and a digit |
| High strength | 10 characters | A lowercase letter, an uppercase letter, a digit and a symbol |
Every policy allows at most 64 bytes. An accented or non-English character counts as two bytes or more.
Set the password yourself
Section titled “Set the password yourself”When email isn’t an option, an administrator can set the password: open Admin, Users, the user, and their Authentication tab, then use Set password. Setting it signs the user out of every session. The Admin API does the same with PUT /api/v1/admin/users/{id}/password.