How to fix fatal: unable to access: NTLM authentication failed in Git

GitINTERMEDIATEMEDIUM

The 'NTLM authentication failed' error occurs when Git cannot authenticate through a corporate proxy server using NTLM (NT LAN Manager) credentials. This typically happens in enterprise environments where proxy servers require Windows domain authentication.

What this error means

This error indicates that Git's underlying HTTP library (libcurl) failed to authenticate with an NTLM-based proxy server. NTLM is a Microsoft authentication protocol commonly used in corporate networks to authenticate users against a Windows domain before allowing internet access. When you execute Git commands that require network access (clone, push, pull, fetch), Git must communicate through your corporate proxy. If the proxy uses NTLM authentication, Git needs to perform a multi-step handshake with the proxy server, providing your Windows domain credentials in a specific encrypted format. The authentication failure can occur for several reasons: 1. **Git/libcurl NTLM support limitations** - Not all versions of Git or its SSL backend fully support NTLM authentication 2. **Credential issues** - Incorrect domain, username, or password 3. **Proxy configuration** - Incorrectly configured proxy URL or authentication method 4. **Network policy** - The proxy server may have specific requirements for NTLM negotiation This is a particularly common problem in corporate or enterprise environments where network security policies require all HTTP/HTTPS traffic to pass through an authenticated proxy server.

How to fix "fatal: unable to access: NTLM authentication failed"

1Install and configure CNTLM as a local proxy

CNTLM (Cntlm Authentication Proxy) is the most reliable solution for NTLM proxy authentication. It acts as a local proxy that handles NTLM authentication on your behalf.

Step 1: Download and install CNTLM
- Windows: Download from [cntlm.sourceforge.net](https://cntlm.sourceforge.net/) or install via Chocolatey:

bash

choco install cntlm

- macOS: Install via Homebrew:

bash

brew install cntlm

- Linux (Debian/Ubuntu):

bash

sudo apt-get install cntlm

Step 2: Generate password hash

bash

cntlm -H -d YOUR_DOMAIN -u YOUR_USERNAME
# Enter your password when prompted
# Copy the output hash values

Step 3: Configure cntlm.ini (Windows) or /etc/cntlm.conf (Linux/macOS)

ini

Username    your_username
Domain      YOUR_DOMAIN
Proxy       corporate-proxy.company.com:8080
NoProxy     localhost, 127.0.0.*, 10.*, 192.168.*
Listen      3128
# Paste the hash values from step 2
PassNTLMv2  ABC123...

Step 4: Start CNTLM

bash

# Windows (as service)
net start cntlm

# Linux/macOS
sudo cntlm -c /etc/cntlm.conf

# Or run in foreground for testing
cntlm -f

Step 5: Configure Git to use CNTLM

bash

git config --global http.proxy http://127.0.0.1:3128
git config --global https.proxy http://127.0.0.1:3128

Important: Use 127.0.0.1 instead of localhost to avoid DNS resolution delays.

2Use Px proxy for automatic Windows authentication

Px is a modern alternative to CNTLM that leverages Windows SSPI for automatic authentication. It doesn't require storing your password.

Install Px:

bash

# Using pip
pip install px-proxy

# Or download the standalone executable from GitHub
# https://github.com/genotrance/px/releases

Run Px:

bash

# Start Px (it will auto-detect your proxy from Windows settings)
px

# Or specify the upstream proxy
px --proxy=corporate-proxy.company.com:8080

# Run on a specific port
px --listen=3128

Configure Git to use Px:

bash

git config --global http.proxy http://127.0.0.1:3128
git config --global https.proxy http://127.0.0.1:3128

Advantages of Px:
- Uses Windows single sign-on (SSPI) - no password storage needed
- Automatically detects proxy settings from Windows/PAC files
- Supports both NTLM and Kerberos authentication
- No configuration file needed in most cases

3Configure Git proxy with domain credentials directly

Git 1.7.10+ has native NTLM support through libcurl. Try configuring the proxy directly with your domain credentials:

Basic proxy configuration:

bash

# Format: http://DOMAIN\username:password@proxy:port
# Note: Three backslashes needed for proper escaping
git config --global http.proxy http://DOMAIN\\\\username:[email protected]:8080

Alternative format (URL-encoded):

bash

# If your domain contains special characters, URL-encode them
# Backslash becomes %5C
git config --global http.proxy http://DOMAIN%5Cusername:[email protected]:8080

Using empty credentials for Windows integrated auth:

bash

# On Windows, empty credentials may trigger SSPI authentication
git config --global http.proxy https://:@proxy.company.com:8080/

Set proxy authentication method explicitly:

bash

# Try NTLM
git config --global http.proxyauthmethod ntlm

# Or try negotiate (Kerberos/NTLM auto-negotiation)
git config --global http.proxyauthmethod negotiate

# Check available methods in your Git build
git config --global http.proxyauthmethod basic

Via environment variable:

bash

# For single commands
HTTPS_PROXY="http://DOMAIN\\username:[email protected]:8080" git clone https://github.com/user/repo.git

4Use Fiddler as an authenticating proxy

Fiddler is a web debugging proxy that can automatically add authentication headers. This is useful for troubleshooting and as a workaround.

Step 1: Download and install Fiddler
Download from [telerik.com/fiddler](https://www.telerik.com/fiddler/fiddler-classic) (Fiddler Classic is free)

Step 2: Enable automatic authentication
1. Open Fiddler
2. Go to Rules menu
3. Check Automatically Authenticate

Step 3: Configure upstream proxy (if needed)
1. Go to Tools > Options > Gateway
2. Select Manual Proxy Configuration
3. Enter your corporate proxy address

Step 4: Configure Git to use Fiddler

bash

# Fiddler default port is 8888
git config --global http.proxy http://127.0.0.1:8888
git config --global https.proxy http://127.0.0.1:8888

# Disable SSL verification if Fiddler is decrypting HTTPS
git config --global http.sslVerify false

Note: Remember to revert SSL verification when not using Fiddler:

bash

git config --global http.sslVerify true

5Verify and update Git version

NTLM proxy support has improved significantly in newer Git versions. Ensure you're running a recent version:

Check your Git version:

bash

git --version

Git NTLM support timeline:
- Git 1.7.10+ - Initial NTLM proxy support via libcurl
- Git 2.14+ - Improved proxy authentication handling
- Git 2.26+ - Better credential helper integration

Update Git:

Windows:

bash

# Self-update
git update-git-for-windows

# Or download latest from https://git-scm.com/download/win

macOS:

bash

brew upgrade git

Linux:

bash

# Ubuntu/Debian - get latest stable
sudo add-apt-repository ppa:git-core/ppa
sudo apt update
sudo apt install git

Check SSL backend:

bash

# Git uses libcurl for HTTP operations
# Check what SSL library it was built with
git config --global http.sslbackend

# On Windows, you may need to switch to Schannel
git config --global http.sslBackend schannel

6Use NTLMAPS for Linux/macOS environments

NTLMAPS (NTLM Authorization Proxy Server) is a Python-based proxy that handles NTLM authentication, useful for non-Windows systems.

Install NTLMAPS:

bash

# Download from sourceforge
wget https://downloads.sourceforge.net/project/ntlmaps/ntlmaps/ntlmaps-0.9.9.0.1/ntlmaps-0.9.9.0.1.tar.gz
tar xzf ntlmaps-0.9.9.0.1.tar.gz
cd ntlmaps-0.9.9.0.1

Configure server.cfg:

ini

LISTEN_PORT:5865
PARENT_PROXY:corporate-proxy.company.com
PARENT_PROXY_PORT:8080
NT_DOMAIN:YOUR_DOMAIN
USER:your_username
PASSWORD:your_password

Start NTLMAPS:

bash

python main.py

Configure Git:

bash

git config --global http.proxy http://127.0.0.1:5865
git config --global https.proxy http://127.0.0.1:5865

Note: NTLMAPS is older and less maintained than CNTLM. Use CNTLM if possible.

7Debug and diagnose the authentication failure

Enable verbose output to understand exactly where authentication is failing:

Enable Git HTTP debugging:

bash

# Full HTTP tracing
GIT_CURL_VERBOSE=1 git clone https://github.com/user/repo.git

# General Git tracing
GIT_TRACE=1 git clone https://github.com/user/repo.git

# All debugging combined
GIT_TRACE=1 GIT_CURL_VERBOSE=1 GIT_TRACE_PACKET=1 git clone https://github.com/user/repo.git 2>&1 | tee git-debug.log

Check current proxy configuration:

bash

# Show all Git config related to proxy
git config --global --list | grep -i proxy

# Show HTTP config
git config --global --list | grep -i http

Test proxy connectivity:

bash

# Test with curl directly
curl -v --proxy http://proxy.company.com:8080 --proxy-ntlm -U "DOMAIN\\username:password" https://github.com

# Test with empty auth (Windows integrated)
curl -v --proxy http://proxy.company.com:8080 --proxy-ntlm -U ":" https://github.com

Common debug output clues:
- 407 Proxy Authentication Required - Credentials not accepted
- Connection timed out - Proxy address or port incorrect
- SSL handshake failed - Certificate or TLS issue
- NTLM handshake failed - Domain or credential format issue

8Clear cached credentials and reset configuration

Stale credentials can cause persistent authentication failures:

Clear Git proxy configuration:

bash

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

# Verify they're cleared
git config --global --list | grep proxy

Clear Windows Credential Manager:

powershell

# List all credentials
cmdkey /list

# Delete proxy credentials
cmdkey /delete:targetname

# Or open Credential Manager GUI
control /name Microsoft.CredentialManager

Clear environment variables:

bash

# Check what's set
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $http_proxy
echo $https_proxy

# Unset them
unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy

Reset CNTLM configuration (if using):

bash

# Regenerate password hash
cntlm -H -d YOUR_DOMAIN -u YOUR_USERNAME

# Update cntlm.ini with new hash
# Restart CNTLM service

Advanced notes

### Understanding NTLM Authentication Flow

NTLM authentication is a challenge-response protocol that works in three steps:
1. Type 1 (Negotiate) - Client sends initial request to proxy
2. Type 2 (Challenge) - Proxy responds with a challenge containing server info
3. Type 3 (Authenticate) - Client responds with encrypted credentials based on challenge

If any step fails, you get the "NTLM authentication failed" error.

### NTLMv1 vs NTLMv2

Modern corporate environments typically require NTLMv2 for security:

bash

# In CNTLM, ensure you're using NTLMv2 hash
cntlm -H -d DOMAIN -u username
# Use the PassNTLMv2 value, not PassNT or PassLM

### Kerberos/Negotiate Authentication

Some proxies use Negotiate authentication which can use either Kerberos or NTLM:

bash

# Try negotiate method
git config --global http.proxyauthmethod negotiate

# This works best when:
# - You're on a domain-joined Windows machine
# - Kerberos tickets are valid (klist command to check)

### Corporate Proxy PAC Files

Many corporations use PAC (Proxy Auto-Configuration) files:

bash

# Find your PAC file URL
# Windows: Internet Options > Connections > LAN Settings

# Px can parse PAC files automatically
px --pac=http://proxy.company.com/proxy.pac

### Security Considerations

When configuring proxy authentication:

1. Never store plain-text passwords in Git config
- Use CNTLM/Px with hashed passwords instead
- Environment variables are visible in process lists

2. Restrict access to credential files

bash

chmod 600 ~/.cntlm.conf
   chmod 600 ~/.git-credentials

3. Don't expose your proxy to the network

ini

# CNTLM - only listen on localhost
   Listen 127.0.0.1:3128
   # NOT: Listen 0.0.0.0:3128

### SSH as Alternative

If proxy NTLM issues persist, SSH through port 443 often bypasses corporate proxies:

bash

# ~/.ssh/config
Host github.com
    HostName ssh.github.com
    Port 443
    User git

# Change remote to SSH
git remote set-url origin [email protected]:user/repo.git

### Troubleshooting CNTLM

bash

# Test CNTLM authentication
cntlm -f -c /etc/cntlm.conf -v

# Common issues:
# - "Credentials rejected" - Wrong password hash
# - "Connection refused" - Wrong proxy address
# - "Timeout" - Firewall blocking connection

# Generate new hash after password change
cntlm -H -d DOMAIN -u username

### Git for Windows SSL Backend

Git for Windows can use different SSL backends:

bash

# Use Windows native SSL (better NTLM support)
git config --global http.sslBackend schannel

# Or use OpenSSL
git config --global http.sslBackend openssl

Schannel often works better with corporate proxies as it uses Windows native certificate stores and authentication.

How to fix fatal: unable to access: NTLM authentication failed in Git

What this error means

Typical symptoms

Common causes

How to fix "fatal: unable to access: NTLM authentication failed"

Advanced notes

Related errors

Official resources & further reading