Technical Guide to Resolving "fatal: Invalid credentials" Error When Pushing to Bitbucket

Problem Background and Error Analysis

When pushing code to a Bitbucket repository using Git, developers may encounter the "fatal: Invalid credentials" error. This error typically manifests as follows:

git push -u origin master

fatal: Invalid credentials
Password for 'https://username@bitbucket.org':
remote: Bitbucket Cloud recently stopped supporting account passwords for Git authentication.
remote: See our community post for more details: https://atlassian.community/t5/x/x/ba-p/1948231
remote: App passwords are recommended for most use cases and can be created in your Personal settings:
remote: https://bitbucket.org/account/settings/app-passwords/
fatal: Authentication failed for 'https://bitbucket.org/username/demo.git/'

The error message clearly indicates that Bitbucket Cloud has discontinued support for using account passwords for Git authentication. This policy change took effect on March 1, 2022, aimed at enhancing security. Therefore, even if the account password is correct, the traditional authentication method is no longer valid.

Solution: Creating and Using App Passwords

The core method to resolve this issue is to create and use app passwords. App passwords are independent credentials generated for specific applications or scenarios, offering fine-grained permission control. Here are the detailed steps to create an app password:

1. Visit the Bitbucket website and log in to your account.
2. Click the gear icon in the upper right corner and select "Personal Bitbucket settings".
3. Under the "Access management" section, click "App passwords".
4. Click the "Create app password" button.
5. Set a label for the app password, such as "Git CLI" or "JetBrains IDE", to identify its purpose.
6. Select the necessary permissions. For basic Git operations (e.g., pull and push), at least check the "Read" and "Write" permissions under "Repositories". If account management is involved, "Read" permission under "Account" may also be required.
7. Click "Create" to generate the password. Important note: The app password is displayed only once upon generation and cannot be viewed again, so save it immediately and securely.

After generating the app password, you need to use it for authentication in Git command-line or integrated development environments (IDEs). In Git command-line, when prompted for a password, use the app password instead of the account password. In IDEs (e.g., JetBrains series), you typically need to configure the app password in settings or authentication dialogs.

Technical Details and Best Practices

Permission settings for app passwords are crucial. Below is an example code demonstrating how to securely handle app passwords in automated scripts (note: in practice, avoid hardcoding passwords):

# Example: Using environment variables to store app passwords for Git operations
import os
import subprocess

# Retrieve app password from environment variable
app_password = os.environ.get('BITBUCKET_APP_PASSWORD')
if app_password:
    # Build Git command using app password for authentication
    git_command = ['git', 'push', 'origin', 'master']
    env = os.environ.copy()
    env['GIT_ASKPASS'] = 'echo'  # Simplify authentication flow
    # Note: In practice, use more secure methods like Git credential storage
    subprocess.run(git_command, env=env)
else:
    print("Error: App password environment variable not set")

Additionally, it is recommended to regularly review and update app passwords, deleting unnecessary ones to reduce security risks. In team collaboration environments, ensure all members understand and use app passwords to avoid workflow disruptions due to authentication issues.

Troubleshooting and Common Issues

If problems persist after following the above steps, check the following aspects:

• Confirm that the username used is correct. Check your username in Bitbucket's "Account settings" and use it during authentication.
• Verify that the app password permissions are sufficient. For example, push operations require "Write" permission under "Repositories".
• Clear old Git credential caches. Run git credential reject in the command-line or use the system credential manager to delete old records.
• For IDE users, ensure that authentication information is updated in the IDE settings and restart the IDE for changes to take effect.

By systematically applying these steps, you can effectively resolve the "fatal: Invalid credentials" error and ensure smooth integration between Git and Bitbucket.