doc/user/profile/account/two_factor_authentication_troubleshooting.md
{{< details >}}
{{< /details >}}
HTTP Basic: Access denied. If a password was provided for Git authentication ...When making a request, you might get an error that states:
HTTP Basic: Access denied. If a password was provided for Git authentication,
the password was incorrect or you're required to use a token instead of a password.
If a token was provided, it was either incorrect, expired, or improperly scoped.
This error occurs when:
To resolve this error:
read_repository or write_repositoryread_registry or write_registryread_registry and write_registryinvalid pin codeAn invalid pin code error can indicate that there is a time sync issue between the authentication
application and the GitLab instance itself.
To resolve this issue, turn on time synchronization for the device that generates your 2FA codes.
{{< tabs >}}
{{< tab title="Android" >}}
{{< /tab >}}
{{< tab title="iOS" >}}
{{< /tab >}}
{{< /tabs >}}
Permission denied (publickey) when generating recovery codesYou might get an error that states Permission denied (publickey).
This issue occurs if you are using a non-default SSH key pair file path and attempt to generate recovery codes using SSH.
To resolve this, configure SSH to point to a different directory using ssh-agent.
When working with email OTP, you might encounter the following issues.
[!note] From April 2026, multi-factor authentication is mandatory on GitLab.com for any sign-in or API request that uses a username and password. Email OTP is the mandatory second factor on GitLab.com if another factor is not configured.
The Enhanced Authentication Coming Soon banner signals that GitLab will begin to enforce email one-time passcodes for your account at password-based sign-in. Users who sign in with SSO or who have 2FA already configured are unaffected.
This banner appears 14 days before enforcement. 7 days before enforcement, GitLab sends you a one-time passcode at each password-based sign-in. You can skip passcode entry during this period.
When the enforcement date passes, you must enter a one-time passcode at every password-based sign-in. To avoid being locked out, ensure you can access your primary email address, or change your primary email address.
Check your spam folder. On GitLab.com, emails are sent from [email protected]
and can be verified as genuine.
If your code expires, you can request a new code. From the sign-in page, select Resend code.
If you cannot access your primary email address, use another email address associated with your account. From the sign-in page, select Send a code to another address associated with this account.
If you cannot access any associated email address:
You cannot disable email OTP if:
You cannot enable email OTP if:
When you enabled a one-time password (OTP) authenticator, GitLab provided you with a series of recovery codes. You can use these codes to sign in to your account.
To use a recovery code:
After you use a recovery code, you cannot use the same code again. Your other recovery codes remain valid.
If you can still access your account, you can regenerate your recovery codes through your user settings.
To regenerate recovery codes with the UI:
[!note] Every time you regenerate 2FA recovery codes, save them. You can't use any previously created 2FA codes.
If you added an SSH key to your GitLab account, you can regenerate your recovery codes with SSH.
Prerequisites:
[!note] You cannot use
gitlab-sshdto regenerate recovery codes.
To regenerate recovery codes with SSH:
In the terminal, verify SSH agent is running on your device.
On macOS and Linux, run the following command:
eval "$(ssh-agent -s)"
On Microsoft Windows, run the following command in PowerShell:
Set-Service -Name ssh-agent -StartupType Automatic; Start-Service ssh-agent
For more information, see SSH setup instructions for Windows.
Load the private key into SSH agent with the following command:
On macOS and Linux, run the following command:
ssh-add <directory to private SSH key>
For more information, see Use SSH keys in another directory.
Open an SSH connection with the following command:
ssh [email protected] 2fa_recovery_codes
On GitLab Self-Managed instances, replace gitlab.com with the GitLab server hostname (gitlab.example.com).
On the confirmation message, enter yes.
Save the recovery codes that GitLab generates. Your previous recovery codes are no longer valid.
On the sign-in page, enter your username or email, and password.
When prompted for a two-factor code, enter one of your new recovery codes.
After signing in, immediately set up 2FA with a new device.
In addition to the GitLab recovery codes, many authenticator apps offer their own backup and recovery methods. If you lose your device, you may be able to restore your 2FA codes by logging into your authenticator app on a new device, provided you enabled backup features beforehand.
Prerequisites:
[!note] GitLab recommends using recovery codes as your primary recovery method. Make sure you save your recovery codes when you enable 2FA.
GitLab Support cannot assist with recovery issues related to third-party authenticator apps.
For more information, see the documentation for your specific authenticator app. Documentation for common authenticators is available through the following locations:
{{< details >}}
{{< /details >}}
If the previous recovery options do not work, you can create a support request to disable 2FA for your account. This service is only available for accounts with a GitLab.com subscription.
GitLab Support cannot reset 2FA for Free accounts. If you cannot recover your 2FA method, you will be permanently locked out of your account and must create a new one. For more information, see the blog announcement.
To create a support request:
After you regain access to your account, re-enable 2FA as soon as possible to keep your account secure.
If you are a top-level group Owner on a paid plan, you can disable 2FA for enterprise users. For more information, see disable 2FA for enterprise users.