Release Incident Playbook

Password reset link broken: symptoms, cause, and the test that catches it

Password reset emails link to a wrong or expired route after a routing change.

Password reset link broken is documented by 3 accepted public reports from 3 organisations, 2 of them published in the last 5 years.

  • Likelihood: low (2 public reports in 5 years)
  • Impact: medium (3 of 3 reports: availability)

3 public reports · verified 2026-10-21

Symptoms

User-visible

  • The link in the password reset email opened the screen for requesting a reset email instead of the reset form.[1]
  • Users who followed the emailed link could not reset their password.[1]
  • The reset email showed the raw template variable where the reset URL should have been.[2]
  • The reset link pointed at the old domain and returned a 404 error.[3]
  • Replacing the old domain with the new one by hand made the reset link work.[3]

Monitoring-visible

  • The mail log showed the reset URL variable left unreplaced in the outgoing message.[2]
  • A support forum post comparing the new release with the previous working version was the first signal of the malformed link.[1]
  • A support forum report, later linked from the issue, was the first signal of the missing reset URL.[2]
  • A user report filed in the issue tracker was the first signal of the link to the old domain.[3]

Root causes

  1. stage: code Improper escaping of the reset link query string produced an invalid entity in the URL, so the link opened the request screen instead of the reset form.[1]
  2. stage: code A template change replaced the reset URL variable with a variable name that did not exist, so the email went out without a substituted link.[2]
  3. stage: migration The template variable rename was not covered by the migration script.[2]
  4. stage: config The application URL still pointed at the pre-migration domain after a host move, so reset emails carried links to the old host.[3]

Public examples

Test classes that catch it

Test classStageLimitationBasis
End-to-end testspre-deployAn end-to-end run in staging builds the reset link from the staging application URL, so it passes while production still points reset links at the pre-migration domain.by design analysis
Unit testspre-mergeA unit test of the reset link builder accepts whatever base URL it is given, so it misses an application URL left on the old host.by design analysis
Configuration and environment testspost-deployA check of the application URL passes when the host is right, so it misses a query string escaped into an invalid entity or a template variable that was never substituted.by design analysis

Risk

  • Likelihood: low (2 public reports in 5 years)
  • Impact: medium (3 of 3 reports: availability)
Counts behind the grades
Accepted public reports3
Published in the last 5 years2
Impact stated: availability3

How the grades are computed

Pre-release checklist

  • PR-01
  • PR-02
  • PR-03
  • PR-04
  • PR-05
  • PR-06
  • PR-07

First 30 minutes

  • FM-01
  • FM-02
  • FM-03
  • FM-04
  • FM-05
  • FM-06
  • FM-07
  • FM-08

Download the checklist

What catches this: catalogue entries

Listed because their own documentation or site names end-to-end tests, unit tests, configuration and environment tests on the verification date. Alphabetical. Not a recommendation.

Tools whose documentation names these test classes

Providers whose site names these test classes

Only on this page

Users found password reset link broken and reported it on a support forum in report [1], on a second support forum in report [2] and in an issue tracker in report [3]. The broken part sits inside an email. The reset request succeeds and the email is sent, so the request endpoint shows no error for a canary or synthetic check to flag. In one report the mail log carried the unreplaced variable, which makes the outgoing message itself the place to assert on [2].

In report [3], the reset email carried the pre-migration domain because the application URL was not updated after the tracker moved hosts. An end-to-end run in staging builds links from the staging base URL, so it passes. The link worked once a user swapped in the new domain by hand, which places this case in config rather than in the reset code. The check that catches it reads the production application URL or follows a link from a real production reset email after the move.

Questions

What causes password reset link broken?

Two reports trace it to code: a query string escaped into an invalid entity [1] and a template variable renamed to one that did not exist [2]. A third traces it to config: an application URL left on the old domain after a host move [3].

What are the symptoms of password reset link broken?

The emailed link opens the wrong screen [1], shows a raw template variable instead of a URL [2], or returns a 404 on the old domain [3]. The user cannot reset the password from that email.

Why did tests not catch password reset link broken?

None of the three reports names a test class that ran on the reset flow. In each report, a user report was the first signal. A staging end-to-end run would also miss the old-domain case because it builds links from the staging URL.

Which test class catches password reset link broken, and what does it miss?

End-to-end tests, unit tests and configuration and environment tests are listed, all with the by-design label. Unit tests of the link builder miss an application URL left on the old host.

What should be checked before a release to prevent password reset link broken?

PR-01 follows a real reset email link in staging to the reset form. PR-06 confirms the production base URL matches the domain users reach after a move.

Should a team roll back or fix forward when password reset link broken happens?

A wrong host is fixed forward by correcting the application URL; one report resolved that case about two hours after it was filed [3]. A malformed link was fixed forward in a new version the same day [1].

Release Incident Playbook (2026). Password reset link broken: symptoms, cause, and the test that catches it, content version 1.0.0. https://releasefailures.com/incidents/password-reset-link-broken/. Accessed 2026-10-21.