Add "Troubleshooting two-factor authentication issues" article (#57481)

Co-authored-by: Joe Clark <[email protected]>
Co-authored-by: Jessica <[email protected]>

Author: 3 people

content/authentication/securing-your-account-with-two-factor-authentication-2fa/accessing-github-using-two-factor-authentication.md

@@ -25,7 +25,7 @@ If you access {% data variables.product.github %} using other methods, such as t
 
 {% else %}
 
-With two-factor authentication enabled, you'll need to provide an authentication code{% ifversion fpt or ghec %}, tap a notification in GitHub Mobile,{% endif %} or use a security key when accessing {% data variables.product.github %} through your browser. If you access {% data variables.product.github %} using other methods, such as the API or the command line, you'll need to use an alternative form of authentication. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github).
+With two-factor authentication enabled, you'll need to provide an authentication code{% ifversion fpt or ghec %}, tap a notification in GitHub Mobile,{% endif %} or use a passkey or security key when accessing {% data variables.product.github %} through your browser. If you access {% data variables.product.github %} using other methods, such as the API or the command line, you'll need to use an alternative form of authentication. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github).
 
 {% endif %}
 
@@ -101,20 +101,12 @@ Enabling 2FA doesn't change how you authenticate to {% data variables.product.gi
 
 ## Troubleshooting
 
-If you lose access to your two-factor authentication credentials, you can use your recovery codes or another recovery method (if you've set one up) to regain access to your account. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials).
-
-{% ifversion fpt or ghec %}
-
-> [!NOTE]
-> {% data reusables.two_fa.unlink-email-address %}
-
-{% endif %}
-
-If your authentication fails several times, you may wish to synchronize your phone's clock with your mobile provider. Often, this involves checking the "Set automatically" option on your phone's clock, rather than providing your own time zone.
+If you are receiving a "Two-factor authentication failed" error when authenticating with 2FA, the authentication code you are entering is incorrect. You can try troubleshooting your configured authentication methods before attempting account recovery. See [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/troubleshooting-two-factor-authentication-issues).
 
 ## Further reading
 
 * [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication)
 * [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication)
 * [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods)
+* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/troubleshooting-two-factor-authentication-issues)
 * [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials)

content/authentication/securing-your-account-with-two-factor-authentication-2fa/changing-your-two-factor-authentication-method.md

@@ -1,6 +1,6 @@
 ---
 title: Changing your two-factor authentication method
-intro: You can change two-factor authentication (2FA) method without disabling 2FA entirely.
+intro: You can change your two-factor authentication (2FA) method without disabling 2FA entirely.
 redirect_from:
   - /articles/changing-two-factor-authentication-delivery-methods
   - /articles/changing-two-factor-authentication-delivery-methods-for-your-mobile-device

content/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication.md

@@ -52,7 +52,7 @@ If you're a member of an {% data variables.enterprise.prodname_emu_enterprise %}
 {% endif %}
 
 > [!NOTE]
-> You can reconfigure your 2FA settings without disabling 2FA entirely, allowing you to keep both your recovery codes and your membership in organizations that require 2FA.
+> You can reconfigure your 2FA settings without disabling 2FA entirely, allowing you to keep both your recovery codes and your membership in organizations that require 2FA. See [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/changing-your-two-factor-authentication-method).
 
 ## Configuring two-factor authentication using a TOTP app
 
@@ -141,5 +141,6 @@ After signing in and turning on push notifications, you can now use your device
 * [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication)
 * [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods)
 * [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/accessing-github-using-two-factor-authentication)
+* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/troubleshooting-two-factor-authentication-issues)
 * [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials)
 * [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)

content/authentication/securing-your-account-with-two-factor-authentication-2fa/index.md

@@ -14,13 +14,14 @@ topics:
   - 2FA
 children:
   - /about-two-factor-authentication
+  - /about-mandatory-two-factor-authentication
   - /configuring-two-factor-authentication
   - /configuring-two-factor-authentication-recovery-methods
   - /accessing-github-using-two-factor-authentication
-  - /recovering-your-account-if-you-lose-your-2fa-credentials
-  - /changing-your-two-factor-authentication-method
-  - /about-mandatory-two-factor-authentication
   - /countries-where-sms-authentication-is-supported
+  - /changing-your-two-factor-authentication-method
+  - /troubleshooting-two-factor-authentication-issues
+  - /recovering-your-account-if-you-lose-your-2fa-credentials
   - /disabling-two-factor-authentication-for-your-personal-account
 shortTitle: Secure your account with 2FA
 ---

content/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials.md

@@ -35,6 +35,9 @@ Use one of your recovery codes to automatically regain entry into your account.
 {% data reusables.accounts.prompt-for-2fa-recovery-code %}
 1. Type one of your recovery codes, then click **Verify**.
 
+> [!NOTE]
+> If you are receiving a "Recovery code authentication failed" error when using a recovery code, the code you are entering is invalid. You can try troubleshooting your recovery codes. See [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/troubleshooting-two-factor-authentication-issues).
+
 ## Authenticating with a passkey
 
 If you have added a passkey to your account, you can use your passkey to automatically regain access to your account. Passkeys satisfy both password and 2FA requirements, so you don't need to know your password in order to recover your account. See [AUTOTITLE](/authentication/authenticating-with-a-passkey/about-passkeys).
@@ -101,4 +104,5 @@ If you have exhausted your recovery options, you can unlink your email address f
 
 ## Further reading
 
+* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/troubleshooting-two-factor-authentication-issues)
 * [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods)

content/authentication/securing-your-account-with-two-factor-authentication-2fa/troubleshooting-two-factor-authentication-issues.md

@@ -0,0 +1,100 @@
+---
+title: Troubleshooting two-factor authentication issues
+intro: 'If you are having trouble authenticating with 2FA, you can try troubleshooting your configured authentication methods.'
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '*'
+topics:
+  - 2FA
+  - Authentication
+shortTitle: Troubleshooting 2FA
+---
+
+If you are receiving a "Two-factor authentication failed" error when authenticating with two-factor authentication (2FA), the authentication code you are entering is incorrect. You can try troubleshooting your configured authentication methods before attempting account recovery.
+
+## Troubleshooting authentication using a TOTP app
+
+### Use the right app
+
+When authenticating with a TOTP app, {% data variables.product.github %} does not send you anything; you need to provide {% data variables.product.github %} with a valid code, based on the secret key that you saved to your TOTP app when 2FA was set up. Find the app or program that you originally used to setup 2FA and retrieve the authentication code from there.
+
+### Check your device’s date and time
+
+TOTP codes are time‑based. If the clock on your phone or computer is out of sync with {% data variables.product.github %}'s server, the code will be invalid. Ensure that your device’s date, time and time zone are set automatically by your network provider. On most mobile devices, this means turning on the **Set automatically** option.
+
+### Wait for a new code and enter it promptly
+
+Codes change every 30 seconds. Open your TOTP app, wait for the next code to appear and enter it immediately. Avoid typing spaces or extra characters as these will make the code invalid.
+
+### Verify you’re using the correct account entry
+
+Most TOTP apps support multiple accounts for a single website. Make sure you’re reading the code from the correct entry in the app. Codes generated for a different account will not work.
+
+### Restore from a TOTP backup
+
+Many TOTP apps support cloud backup or key export. If you lose or reset your device, you may be able restore your 2FA data from the app’s backup to a new device. Consult your app’s documentation for instructions.
+
+{% ifversion fpt or ghec %}
+
+## Troubleshooting authentication using text messages
+
+### Confirm that you can receive text messages
+
+Make sure your device and cellular plan is capable of receiving Short Message Service (SMS) messages. Some "data-only" phone plans and tablet devices connected to a cellular network may not support receiving text messages. Check with your provider and device manufacturer.
+
+Carrier rates may apply for received SMS messages. Ensure your cellular plan covers potential charges.
+
+Disable "Do Not Disturb" mode or spam‑filtering apps that might block receipt of authentication codes.
+
+### Check that you have cellular coverage
+
+Receiving text messages generally requires a strong network signal. Ensure you have adequate coverage before requesting an authentication code.
+
+### Power cycle your phone
+
+Turning your phone off and on will re-register the device with the network, which may resolve some deliverability issues. Enabling and disabling an "Airplane Mode" may also be sufficient, but power cycling your phone is more reliable.
+
+### Consult with your cellular provider
+
+Check with your cellular provider or carrier to see if there are any local outages or delivery issues in your area. They may also be able to investigate delivery issues for your connection. Provide them with the SMS number configured on your {% data variables.product.github %} account and the time that you requested an authentication code from {% data variables.product.github %}.
+
+> [!NOTE]
+> {% data variables.product.github %}, along with our SMS delivery partners, proactively monitors our SMS deliverability success rates. Periods of low-deliverability that would indicate a widespread issue are promptly investigated. You can check active and historical incidents affecting SMS delivery in your region on [{% data variables.product.github %}'s status page](https://githubstatus.com).
+
+{% endif %}
+
+## Recovering your account if troubleshooting doesn't help
+
+If you have tried troubleshooting and you are still having trouble, you can try authenticating with another method, such as a passkey, {% ifversion fpt or ghec %}{% data variables.product.prodname_mobile %},{% endif %} or a security key, if pre-configured on the account. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/accessing-github-using-two-factor-authentication).
+
+{% ifversion fpt or ghec %}
+
+> [!WARNING]
+> For security reasons, {% data variables.contact.github_support %} cannot assist with troubleshooting your 2FA methods, including SMS delivery.
+
+{% endif %}
+
+If you don't have another authentication method, you will need to try account recovery. For more information about account recovery, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials).
+
+## Troubleshooting using recovery codes
+
+If you are receiving a "Recovery code authentication failed" error when using a recovery code, the code you are entering is invalid. You can try troubleshooting your recovery codes.
+
+### Use one code at a time
+
+A set of recovery codes contains more than one code. A single code is 10 alphanumeric characters with a hyphen in the middle: `xxxxx-yyyyy`.
+
+### Try using a different code
+
+Each code is single-use only: once it has been used to authenticate, it cannot be used again. Try using a different code from the set.
+
+### Check you're using the right set of codes
+
+When 2FA is disabled and re-enabled, a new set of codes are created which invalidates the previous set. Recovery codes are also invalidated whenever a new set of codes is generated. Even if you think you might not have another set of codes, you could try searching for them in your devices, backups, and password managers. They will have the default filename `github-recovery-codes.txt`.
+
+## Further reading
+
+* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication)
+* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/accessing-github-using-two-factor-authentication)
+* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials)

data/reusables/accounts/prompt-for-2fa-recovery-code.md

@@ -1,5 +1,9 @@
-1. Navigate to [https://github.com/login](https://github.com/login).
+1. Navigate to {% data variables.product.login_url %}.
 1. To prompt two-factor authentication, type your username and password, then click **Sign in**.
+{% ifversion fpt or ghec %}
+
    > [!NOTE]
-   > If you have linked a Google account to your {% data variables.product.prodname_dotcom %} account, you can sign-in with your social login instead of using your password.
+   > If you have linked a social account to your {% data variables.product.github %} account, you can sign-in with your social login instead of using your password.
+
+{% endif %}
 1. Under "More options", click **2FA recovery code**.

data/reusables/two_fa/support-may-not-help.md

@@ -1 +1 @@
-For security reasons, {% data variables.product.company_short %} Support [will not be able to restore access to accounts](/free-pro-team@latest/site-policy/other-site-policies/github-account-recovery-policy) with two-factor authentication enabled if you lose your two-factor authentication credentials or lose access to your account recovery methods.
+For security reasons, {% data variables.contact.github_support %} [will not be able to restore access to accounts](/free-pro-team@latest/site-policy/other-site-policies/github-account-recovery-policy) with two-factor authentication enabled if you lose your two-factor authentication credentials or lose access to your account recovery methods.

data/variables/product.yml

@@ -237,7 +237,7 @@ prodname_learning_link: 'https://skills.github.com/'
 prodname_roadmap: 'GitHub public roadmap'
 prodname_roadmap_link: 'https://github.com/github/roadmap#github-public-roadmap'
 
-# GitHub support
+# GitHub Support plans
 standard_support_plan: 'Standard plan'
 premium_support_plan: 'Premium plan'
 premium_plus_support_plan: 'Premium Plus plan / GitHub Engineering Direct'
@@ -334,6 +334,12 @@ pricing_url: 'https://github.com/pricing'
 pricing_link: '[GitHub Pricing](https://github.com/pricing)'
 raw_github_com: >-
   {% ifversion fpt or ghec %}raw.githubusercontent.com{% else %}HOSTNAME/user/repo/raw{% endif %}
+login_url: >-
+  {%- ifversion fpt or ghec %}
+  [`https://github.com/login`](https://github.com/login)
+  {%- elsif ghes %}
+  `http(s)://HOSTNAME/login`
+  {%- endif %}
 # GitHub Enterprise Server past versions
 current-340-version: '11.10.354'