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

GitINTERMEDIATEMEDIUMUpdated May 28, 2026· 413 views

The 'Authentication failed (proxy requires basic auth)' error means Git's HTTP proxy is rejecting requests because it needs credentials. Fix it by supplying proxy username/password and setting http.proxyAuthMethod.

Quick fix

Fixes fatal: unable to access: Authentication failed (proxy requires basic auth)

# Configure HTTP proxy with credentials
git config --global http.proxy http://username:password@proxy.example.com:8080

# Configure HTTPS proxy with credentials
git config --global https.proxy http://username:password@proxy.example.com:8080
  1. Configure Git proxy with authentication credentials
  2. Set the proxy authentication method to basic
  3. Use environment variables for proxy configuration
  4. Verify and test proxy configuration
git — error
# Configure HTTP proxy with credentials
git config --global http.proxy http://username:password@proxy.example.com:8080
# Configure HTTPS proxy with credentials
git config --global https.proxy http://username:password@proxy.example.com:8080
fatal: unable to access: Authentication failed (proxy requires basic auth)

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 (HTTP 407) 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 configured to send credentials, and in some cases told explicitly to 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 (libcurl)** - Needs configuration to supply proxy credentials - **http.proxyAuthMethod** - Git configuration that controls which authentication scheme is offered to the proxy

Typical symptoms

  • Git clone, fetch, push, or pull fails with 'Authentication failed (proxy requires basic auth)'
  • Git operations work at home but fail at the office behind a corporate network
  • Error message includes HTTP 407 (Proxy Authentication Required)
  • Git operations fail only when using HTTPS URLs, not SSH
  • Commands work in the browser but fail from the command line
  • Git operations time out or fail after a long delay
  • Error appears after switching to a new network or VPN
  • CI/CD pipelines fail when running behind a proxy server

Common causes

  1. Git is not configured with proxy credentials (username and password)
  2. Proxy URL is configured without authentication credentials
  3. Environment variables http_proxy or https_proxy don't include credentials
  4. The http.proxyAuthMethod is not set to 'basic' when the proxy requires it
  5. Git's default 'anyauth' method fails to negotiate with the proxy
  6. Corporate proxy was recently updated to require authentication
  7. Proxy password contains special characters that need URL encoding
  8. An https:// proxy URL is used where the proxy only speaks http:// (or vice versa)

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:password@proxy.example.com:8080

# Configure HTTPS proxy with credentials
git config --global https.proxy http://username:password@proxy.example.com: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

Note that the scheme in the proxy URL (http://) describes how Git talks to the proxy, not the protocol of the repository you are cloning. Most proxies accept plaintext http:// even for HTTPS Git traffic, which it tunnels via CONNECT.

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%40123@proxy.example.com:8080

Heads-up on plaintext storage: these commands write your password in cleartext to ~/.gitconfig. See "Verify and test" below and the Advanced Notes for ways to avoid persisting the password.

2Set the proxy authentication method to basic

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

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

Git's default authentication method is anyauth, which lets libcurl auto-detect the scheme. Some proxies don't respond well to this negotiation and require the explicit basic method.

Important: proxyAuthMethod only selects *which* scheme is used. It does not supply credentials and Git will not interactively prompt you for proxy credentials. You still need credentials in the proxy URL (Step 1) or in the proxy environment variables (Step 3). Without them, authentication still fails even with basic set.

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, and keeps credentials out of ~/.gitconfig:

On Linux/macOS:

bash
# Set proxy for the current session
export http_proxy="http://username:password@proxy.example.com:8080"
export https_proxy="http://username:password@proxy.example.com:8080"
export HTTP_PROXY="$http_proxy"
export HTTPS_PROXY="$https_proxy"

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

To avoid putting the password in your shell history, prompt for it instead:

bash
read -rs PROXY_PASS
export https_proxy="http://username:$PROXY_PASS@proxy.example.com:8080"
export http_proxy="$https_proxy"

On Windows (Command Prompt):

cmd
set http_proxy=http://username:password@proxy.example.com:8080
set https_proxy=http://username:password@proxy.example.com:8080
git clone https://github.com/user/repo.git

On Windows (PowerShell):

powershell
$env:http_proxy = "http://username:password@proxy.example.com:8080"
$env:https_proxy = "http://username:password@proxy.example.com:8080"
git clone https://github.com/user/repo.git

Git (via libcurl) reads these variables automatically, so you may not need any git config proxy settings at all when they are present.

4Verify and test proxy configuration

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

Check current proxy configuration:

bash
# Show 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 (including the 407 response)
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:password@proxy.example.com:8080 https://github.com

If curl succeeds but Git fails, the problem is in Git's proxy configuration rather than the proxy or network itself.

5Configure proxy for specific domains only

If you only need the proxy for certain hosts (e.g., external repositories), you can configure URL-specific proxy settings:

bash
# Use proxy only for GitHub
git config --global http.https://github.com/.proxy http://username:password@proxy.example.com:8080
git config --global http.https://github.com/.proxyAuthMethod basic

# Use proxy only for an internal GitLab
git config --global http.https://gitlab.company.com/.proxy http://username:password@proxy.example.com:8080
git config --global http.https://gitlab.company.com/.proxyAuthMethod basic

Exclude certain hosts from the proxy:

bash
# Bypass the proxy for internal/loopback hosts (Git 2.13+ honors NO_PROXY-style lists)
export no_proxy="localhost,127.0.0.1,.company.internal"

# Or disable the proxy for a specific URL in Git config by setting it empty
git config --global http.https://internal.company.com/.proxy ""

This lets you route external traffic through the proxy while reaching internal resources directly.

6Clear old proxy settings and reconfigure

If you're having persistent issues, clear all proxy settings and start fresh. Use --unset-all to remove any duplicated or URL-specific entries:

bash
# Remove global proxy settings (use --unset-all to clear duplicates)
git config --global --unset-all http.proxy
git config --global --unset-all https.proxy
git config --global --unset-all http.proxyAuthMethod

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

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

> Note: git config --unset fails with "key contains multiple values" if a key was set more than once, which is why --unset-all is preferred here.

Then reconfigure from scratch:

bash
git config --global http.proxy http://username:password@proxy.example.com:8080
git config --global https.proxy http://username:password@proxy.example.com: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), basic auth will not work. Use CNTLM as a local intermediary proxy that handles NTLM for you:

Install CNTLM:

bash
# On Ubuntu/Debian
sudo apt install cntlm

# On macOS
brew install cntlm

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

Generate a password hash first (avoids storing the cleartext password):

bash
cntlm -H -d COMPANY -u your_username
# Enter password when prompted; copy the PassNTLMv2 line into the config below

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

ini
Username    your_username
Domain      COMPANY
# Prefer the hashed value over a plaintext Password line
PassNTLMv2  <hash-from-cntlm-H>
Proxy       proxy.company.com:8080
Listen      3128

Start CNTLM and point Git at it:

bash
# Start CNTLM
sudo systemctl start cntlm

# Configure Git to use the local CNTLM proxy (no credentials needed in Git)
git config --global http.proxy http://127.0.0.1:3128
git config --global https.proxy http://127.0.0.1:3128

CNTLM performs the NTLM handshake with the corporate proxy, and Git connects through it with a simple unauthenticated local proxy URL.

Advanced notes

### Understanding Proxy Authentication Methods

Git passes http.proxyAuthMethod to libcurl to select which scheme is offered to the proxy:

| 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 (CNTLM is often easier) |

### Security Considerations: keeping the password out of plaintext

When you configure http.proxy with embedded credentials, they are stored in cleartext in ~/.gitconfig, and they may also leak into shell history, process listings, and GIT_CURL_VERBOSE output. Important: setting http.proxyAuthMethod basic does not make Git prompt for proxy credentials — Git has no interactive proxy-credential prompt. Credentials must be supplied explicitly. To avoid persisting them in cleartext:

bash
# 1) Supply the password only at runtime via an environment variable
#    (read -s keeps it out of shell history)
read -rs PROXY_PASS
export https_proxy="http://username:$PROXY_PASS@proxy.example.com:8080"
export http_proxy="$https_proxy"
git fetch origin

# 2) Or run the proxy auth through a local helper such as CNTLM (see Step 7),
#    so Git's config only ever contains http://127.0.0.1:3128 with no secret.

Standard Git credential helpers (e.g. git-credential-manager, osxkeychain, wincred) cache credentials for the *remote repository*, not for the *proxy*, so they generally cannot substitute for proxy credentials. Treat embedded-credential proxy URLs as a last resort and prefer environment variables or a local NTLM helper.

### Debugging Proxy Issues

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

# Inspect the proxy negotiation (look for the 407 and Proxy-Authenticate header)
GIT_CURL_VERBOSE=1 git fetch origin 2>&1 | grep -i -e proxy -e 407

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

### Per-Repository Proxy Configuration

You can set proxy settings for a single repository only:

bash
cd /path/to/repo
git config http.proxy http://username:password@proxy.example.com:8080
git config http.proxyAuthMethod basic
# These settings only apply to this repository

### SSH as an Alternative

If proxy configuration remains problematic, SSH may be simpler since it bypasses the HTTP proxy logic:

bash
# Clone via SSH
git clone git@github.com:user/repo.git

# If outbound SSH (port 22) is blocked, tunnel SSH over HTTPS via the proxy.
# 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, prefer storing the full proxy URL (including any credentials) in a secret rather than committing it:

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 Notes

On Windows the credential manager handles remote-repo credentials, not proxy auth, so it usually does not interfere with proxy authentication. If you suspect it does, set the proxy explicitly and test:

powershell
git config --global http.proxy http://username:password@proxy.example.com:8080
git config --global http.proxyAuthMethod basic
git fetch origin

Frequently asked questions

What does "fatal: unable to access: Authentication failed (proxy requires basic a" mean?
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 (HTTP 407) 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 configured to send credentials, and in some cases told explicitly to use the basic authentication method.
How do I fix "fatal: unable to access: Authentication failed (proxy requires basic a"?
The 'Authentication failed (proxy requires basic auth)' error means Git's HTTP proxy is rejecting requests because it needs credentials. Fix it by supplying proxy username/password and setting http.proxyAuthMethod.
What causes "fatal: unable to access: Authentication failed (proxy requires basic a"?
Git is not configured with proxy credentials (username and password) Proxy URL is configured without authentication credentials Environment variables http_proxy or https_proxy don't include credentials
Is the "fatal: unable to access: Authentication failed (proxy requires basic a" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading