Troubleshooting two-factor authentication

Error: 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:

• You have enabled 2FA and attempted to authenticate with a username and password.
• You have not enabled 2FA and attempted to authenticate with an incorrect username or password.
• You have not enabled 2FA and the enforce 2FA for all users setting is active.
• You have not enabled 2FA and the password authentication enabled for Git over HTTP(S) setting is not active.

To resolve this error:

• Use a personal access token with the correct scopes:
  • For Git requests over HTTP(S): read_repository or write_repository
  • For GitLab container registry requests: read_registry or write_registry
  • For dependency proxy requests: read_registry and write_registry
• If you configured LDAP, use an LDAP password.
• Use an OAuth credential helper.

Error: invalid pin code

An 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.

Error: Permission denied (publickey) when generating recovery codes

You 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.

Recovery options and 2FA reset

If you have enabled 2FA and cannot generate codes, use one of the following methods to access your account:

Use a recovery code

When you enabled 2FA, 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:

1. On the GitLab sign-in page, enter your username or email, and password.
2. When prompted for a two-factor code, enter a recovery code.

After you use a recovery code, you cannot use the same code again. Your other recovery codes remain valid.

Generate new recovery codes using SSH

If you added an SSH key to your GitLab account, you can generate a new set of recovery codes with SSH:

1. In a terminal, run:

   ssh git@gitlab.com 2fa_recovery_codes

   On GitLab Self-Managed instances, replace gitlab.com with the GitLab server hostname (gitlab.example.com).

2. On the confirmation message, enter yes.

3. Save the recovery codes that GitLab generates. Your previous recovery codes are no longer valid.

4. On the sign-in page, enter your username or email, and password.

5. 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.

Reset 2FA on your account

If the previous recovery options do not work, and you still cannot sign in to your account, you can create a support request to disable 2FA for your account. After 2FA is disabled, re-enable it as soon as possible to keep your account secure.

This service is only available for accounts with a GitLab.com subscription. For more information, see our blog post.

To create a support request:

1. Go to GitLab Support.
2. Select Submit a Ticket.
3. If possible, sign in to your account.
4. In the issue dropdown list, select GitLab.com user accounts and login issues.
5. Complete the fields in the support form.
6. Select Submit.

Reset 2FA for enterprise users

If you are a top-level group Owner on a paid plan, you can disable 2FA for enterprise users. For more information, see Disable two-factor-authentication.