How to fix fatal: unable to access: Authentication failed (proxy requires basic auth) in Git

GitINTERMEDIATEMEDIUM

The 'Authentication failed (proxy requires basic auth)' error occurs when Git cannot authenticate with a corporate or network proxy server that requires username and password credentials. This is resolved by configuring Git to send basic authentication credentials to the proxy.

What this error means

This error indicates that Git is attempting to connect to a remote repository through an HTTP proxy server, but the proxy is rejecting the connection because it requires authentication credentials that Git is not providing. When Git makes an HTTPS request through a proxy, the proxy server may require you to authenticate before allowing the connection to pass through. If the proxy uses "basic auth" (HTTP Basic Authentication), Git needs to be explicitly configured to send credentials and use the basic authentication method. The proxy acts as an intermediary between your machine and the remote Git server (GitHub, GitLab, etc.). Corporate networks often use authenticated proxies to control and monitor internet access. Without proper configuration, Git doesn't know how to authenticate with this middleman, resulting in the "Authentication failed" error. Key components involved: - **HTTP proxy server** - The network gateway requiring authentication - **Git's HTTP client** - Needs configuration to supply proxy credentials - **proxyAuthMethod** - Git configuration that controls how authentication is sent to the proxy

How to fix "fatal: unable to access: Authentication failed (proxy requires basic auth)"

1Configure Git proxy with authentication credentials

Set up Git to use your proxy server with your username and password included:

bash

# Configure HTTP proxy with credentials
git config --global http.proxy http://username:[email protected]:8080

# Configure HTTPS proxy with credentials
git config --global https.proxy http://username:[email protected]:8080

Replace the values:
- username - Your proxy username (often your corporate/AD username)
- password - Your proxy password
- proxy.example.com - Your proxy server hostname
- 8080 - Your proxy server port

If your password contains special characters, URL-encode them:
- @ becomes %40
- # becomes %23
- ! becomes %21
- $ becomes %24
- & becomes %26

For example, if your password is Pass@123:

bash

git config --global http.proxy http://username:Pass%[email protected]:8080

2Set the proxy authentication method to basic

Some proxy servers require Git to explicitly use basic authentication. Set the proxyAuthMethod configuration:

bash

# Force Git to use basic authentication with the proxy
git config --global http.proxyAuthMethod basic

This is particularly important because Git's default authentication method is anyauth, which tries to auto-detect the correct method. Some proxies don't respond well to this negotiation and require the explicit basic auth method.

Available authentication methods:
- anyauth - Auto-detect (default, but may fail with some proxies)
- basic - HTTP Basic Authentication (most common for corporate proxies)
- digest - HTTP Digest Authentication
- negotiate - SPNEGO/Kerberos negotiation
- ntlm - Windows NTLM authentication

After setting this, try your Git operation again:

bash

git fetch origin

3Use environment variables for proxy configuration

Alternatively, you can set proxy settings using environment variables. This is useful for temporary configuration or CI/CD pipelines:

On Linux/macOS:

bash

# Set proxy for the current session
export http_proxy="http://username:[email protected]:8080"
export https_proxy="http://username:[email protected]:8080"
export HTTP_PROXY="$http_proxy"
export HTTPS_PROXY="$https_proxy"

# Now run your Git command
git clone https://github.com/user/repo.git

On Windows (Command Prompt):

cmd

set http_proxy=http://username:[email protected]:8080
set https_proxy=http://username:[email protected]:8080
git clone https://github.com/user/repo.git

On Windows (PowerShell):

powershell

$env:http_proxy = "http://username:[email protected]:8080"
$env:https_proxy = "http://username:[email protected]:8080"
git clone https://github.com/user/repo.git

To make these permanent, add them to your shell profile (~/.bashrc, ~/.zshrc) or Windows environment variables.

4Verify and test proxy configuration

After configuring the proxy, verify your settings and test the connection:

Check current proxy configuration:

bash

# Show all proxy-related Git configuration
git config --global --get http.proxy
git config --global --get https.proxy
git config --global --get http.proxyAuthMethod

# Show all Git configuration with locations
git config --list --show-origin | grep -i proxy

Test the connection with verbose output:

bash

# Enable curl verbose mode to see connection details
GIT_CURL_VERBOSE=1 git ls-remote https://github.com/git/git.git

# Or enable full Git tracing
GIT_TRACE=1 GIT_CURL_VERBOSE=1 git fetch origin

Test with curl directly (to isolate Git issues):

bash

# Test proxy connection with curl
curl -v --proxy http://username:[email protected]:8080 https://github.com

If curl works but Git doesn't, the issue is with Git's proxy configuration.

5Configure proxy for specific domains only

If you only need to use the proxy for certain hosts (e.g., internal repositories), you can configure domain-specific proxy settings:

bash

# Use proxy only for GitHub
git config --global http.https://github.com.proxy http://username:[email protected]:8080
git config --global http.https://github.com.proxyAuthMethod basic

# Use proxy only for internal GitLab
git config --global http.https://gitlab.company.com.proxy http://username:[email protected]:8080
git config --global http.https://gitlab.company.com.proxyAuthMethod basic

Exclude certain domains from proxy (no_proxy):

bash

# Don't use proxy for internal servers
export no_proxy="localhost,127.0.0.1,.company.internal"

# Or in Git config
git config --global http.https://internal.company.com.proxy ""

This allows you to bypass the proxy for internal resources that don't require it.

6Clear old proxy settings and reconfigure

If you're having persistent issues, clear all proxy settings and start fresh:

bash

# Remove all global proxy settings
git config --global --unset http.proxy
git config --global --unset https.proxy
git config --global --unset http.proxyAuthMethod

# Remove all proxy settings (including domain-specific)
git config --global --unset-all http.proxy
git config --global --unset-all https.proxy

# Clear environment variables (current session)
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY

# Verify settings are cleared
git config --list | grep -i proxy

Then reconfigure from scratch:

bash

# Set fresh proxy configuration
git config --global http.proxy http://username:[email protected]:8080
git config --global https.proxy http://username:[email protected]:8080
git config --global http.proxyAuthMethod basic

# Test
git ls-remote https://github.com/git/git.git

7Use CNTLM for NTLM proxy authentication

If your corporate proxy uses NTLM authentication (common in Windows/Active Directory environments), you may need CNTLM as an intermediate proxy:

Install CNTLM:

bash

# On Ubuntu/Debian
sudo apt install cntlm

# On macOS
brew install cntlm

# On Windows - download from http://cntlm.sourceforge.net/

Configure CNTLM (`/etc/cntlm.conf` or `cntlm.ini`):

ini

Username    your_username
Domain      COMPANY
Password    your_password  # Or use PassNTLMv2 hash
Proxy       proxy.company.com:8080
Listen      3128

Generate password hash (more secure):

bash

cntlm -H -d COMPANY -u your_username
# Enter password when prompted
# Copy the PassNTLMv2 line to config file

Start CNTLM and configure Git to use it:

bash

# Start CNTLM
sudo systemctl start cntlm

# Configure Git to use local CNTLM proxy
git config --global http.proxy http://127.0.0.1:3128
git config --global https.proxy http://127.0.0.1:3128

CNTLM handles the NTLM authentication with the corporate proxy, and Git connects through it without needing special authentication.

Advanced notes

### Understanding Proxy Authentication Methods

Git supports several proxy authentication methods via http.proxyAuthMethod:

| Method | Description | When to Use |
|--------|-------------|-------------|
| anyauth | Auto-detect (default) | Usually works, but may fail with strict proxies |
| basic | HTTP Basic Auth | Most common for corporate proxies |
| digest | HTTP Digest Auth | More secure than basic, less common |
| negotiate | SPNEGO/Kerberos | Enterprise environments with SSO |
| ntlm | Windows NTLM | Windows domain environments |

### Security Considerations

Password in plain text:
When you configure http.proxy with credentials, they're stored in plain text in ~/.gitconfig. Consider these alternatives:

bash

# Use Git credential helper instead of embedding password
git config --global http.proxyAuthMethod basic
# Then Git will prompt for proxy credentials when needed

# Or use environment variables (don't persist to shell history)
read -s PROXY_PASS
export http_proxy="http://username:[email protected]:8080"

Password in command history:
Avoid typing passwords directly in commands. Use the read approach above or set variables in a separate file.

### Debugging Proxy Issues

bash

# Maximum verbosity for debugging
GIT_TRACE=2 GIT_CURL_VERBOSE=1 GIT_TRACE_PACKET=1 git fetch origin

# Check what Git is sending to the proxy
GIT_TRACE_CURL=1 git fetch origin 2>&1 | grep -i proxy

# Test with curl (bypasses Git's HTTP handling)
curl -v -x http://username:password@proxy:8080 https://github.com/git/git.git/info/refs

### Per-Repository Proxy Configuration

You can set proxy settings for a specific repository only:

bash

cd /path/to/repo
git config http.proxy http://username:[email protected]:8080
git config http.proxyAuthMethod basic
# These settings only apply to this repository

### Git Credential Manager and Proxies

If you use Git Credential Manager (GCM), it may have its own proxy settings:

bash

# Check GCM proxy settings
git credential-manager get
git config --get-all credential.httpProxy

### SSH as an Alternative

If proxy configuration remains problematic, consider using SSH instead of HTTPS:

bash

# Clone via SSH (bypasses HTTP proxy entirely)
git clone [email protected]:user/repo.git

# If SSH is also blocked, you may need to configure SSH over HTTPS:
# In ~/.ssh/config
Host github.com
    Hostname ssh.github.com
    Port 443
    ProxyCommand nc -X connect -x proxy.example.com:8080 %h %p

### CI/CD Pipeline Configuration

For automated pipelines behind a proxy:

yaml

# GitHub Actions example
env:
  http_proxy: ${{ secrets.PROXY_URL }}
  https_proxy: ${{ secrets.PROXY_URL }}

# GitLab CI example
variables:
  http_proxy: "http://proxy.company.com:8080"
  https_proxy: "http://proxy.company.com:8080"

### Windows-Specific Issues

On Windows, credential manager may interfere with proxy authentication:

powershell

# Disable credential manager temporarily
git config --global --unset credential.helper

# Or use wincred with explicit proxy
git config --global credential.helper wincred
git config --global http.proxy http://proxy.example.com:8080
git config --global http.proxyAuthMethod basic

How to fix fatal: unable to access: Authentication failed (proxy requires basic auth) in Git

What this error means

Typical symptoms

Common causes

How to fix "fatal: unable to access: Authentication failed (proxy requires basic auth)"

Advanced notes

Related errors

Official resources & further reading