Start with the visible symptom. Run bin/rails add_auth:doctor to check host wiring, then verify the failing journey.
The email never arrived
Check the account first. The request response is intentionally generic, so it does not reveal whether an address exists or is eligible. Confirm the account address and your eligible callback using your app’s administrative tools.
Check delivery. For the local file adapter, inspect tmp/mail. In a deployed host, check failed jobs, worker health, Action Mailer configuration and provider status. Keep delivery errors enabled.
Check the sweep. Confirm bin/rails add_auth:deliver_pending runs at least once a minute. If a mail callback intentionally cancelled a message, it will not be resent for that issuance. Correct the callback and request a new link.
Verify by requesting a fresh link and following the complete delivered-message-to-session journey. See required services.
A link expired or was already used
Use the newest email. Links are single-use, expire after 20 minutes by default, and are replaced when a new link is issued. Password or email-address changes also invalidate them. Request a fresh link and confirm it once.
The link will not work in this browser
If email_link.same_browser is enabled, use the browser that requested it. A mail client’s embedded browser can have different cookies. Open the link in the requesting browser or request a new one there. Review browser binding.
Sign-in is blocked by captcha
Check that provider keys match the selected provider/mode and that the current hostname is allowed. Confirm provider availability and inspect the server’s sanitized error information. Default outage policy blocks protected actions.
A browser without JavaScript cannot satisfy a JavaScript-dependent widget. Provide an allowed alternative or explain the unavailable state; do not silently weaken the configured policy. See captcha setup.
Users are signed out sooner than expected
Compare both configured limits: absolute lifetime and idle timeout. Check whether a password/address change, revocation, fresh sign-in in the same browser, or session adoption caused the old bearer to become invalid. Read session behavior before extending lifetimes.
The generator cannot find host files
Confirm that bin/rails generate authentication has run. AddAuth expects the Rails-generated user, session and authentication concern. A customized host may require deliberate integration; inspect the generated diff and the exact error.
Still stuck?
Include your installed AddAuth version, Ruby/Rails versions, sanitized error and minimal reproduction in a gem issue. Do not include passwords, session cookies or raw email links. Report possible vulnerabilities through the private security channel.