How to fix fatal: unable to access: SOCKS5 connection to proxy failed in Git

GitBEGINNERMEDIUM

The 'SOCKS5 connection to proxy failed' error occurs when Git cannot establish a connection through your configured SOCKS proxy. This typically happens when the proxy server is not running, the configuration is incorrect, or the protocol (socks5 vs socks5h) is mismatched. The fix usually involves verifying your proxy is active or updating your Git proxy configuration.

What this error means

The "fatal: unable to access: SOCKS5 connection to proxy failed" error indicates that Git is configured to use a SOCKS5 proxy for HTTP/HTTPS connections, but the connection to that proxy cannot be established. Git uses the SOCKS5 protocol to tunnel its traffic through the proxy server, and when this handshake fails, the operation cannot proceed. This error commonly appears when: - A proxy configuration remains in your Git config after you've disconnected from a VPN or stopped running a local proxy (SSH tunnel, Tor, Shadowsocks, etc.) - The proxy server address or port is incorrect - You're using `socks5://` when you should be using `socks5h://` (the "h" variant handles DNS resolution through the proxy) - Network conditions prevent reaching the proxy server The error message comes from the underlying libcurl library that Git uses for HTTP/HTTPS operations. Understanding this helps explain why the same proxy settings work for SSH-based Git operations but fail for HTTPS clones.

How to fix "fatal: unable to access: SOCKS5 connection to proxy failed"

1Check if you actually need a proxy

First, determine if you still need the proxy. If you configured it for a specific network or VPN that you're no longer using, simply remove the proxy settings:

bash

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

# Verify the settings are removed
git config --global --get http.proxy
git config --global --get https.proxy

If these commands return nothing, the global proxy is cleared. Try your Git operation again. If it works, you're done.

2Check all proxy configuration locations

Git proxy settings can exist in multiple places. Check all of them:

bash

# Check global config
git config --global --get http.proxy
git config --global --get https.proxy

# Check local repository config (run in repo directory)
git config --local --get http.proxy
git config --local --get https.proxy

# Check system config
git config --system --get http.proxy

# See all proxy-related settings
git config --list | grep -i proxy

Also check for environment variables:

bash

# Linux/macOS
echo $http_proxy
echo $https_proxy
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $all_proxy

# Windows (PowerShell)
$env:http_proxy
$env:https_proxy

To unset environment variables temporarily:

bash

# Linux/macOS
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY all_proxy

# Windows (PowerShell)
$env:http_proxy = $null
$env:https_proxy = $null

3Verify your proxy server is running

If you do need the proxy, verify it's actually running and accessible:

bash

# Test connection to your proxy (replace with your proxy address and port)
nc -zv 127.0.0.1 1080

# Or use curl to test
curl -v --proxy socks5://127.0.0.1:1080 https://github.com

# On Windows, use PowerShell
Test-NetConnection -ComputerName 127.0.0.1 -Port 1080

Common proxy applications and their default ports:
- SSH dynamic tunnel: Usually 1080 or custom
- Tor: 9050 (SOCKS) or 9150 (Tor Browser)
- Shadowsocks: 1080
- V2Ray/Xray: 10808 or custom
- Clash: 7890

If the proxy isn't running, start it before retrying your Git command.

4Use socks5h instead of socks5

A common issue is using socks5:// when socks5h:// is needed. The "h" variant performs DNS resolution through the proxy server rather than locally:

bash

# Change from socks5 to socks5h for DNS resolution through proxy
git config --global http.proxy socks5h://127.0.0.1:1080
git config --global https.proxy socks5h://127.0.0.1:1080

This is especially important when:
- You're behind a firewall that also blocks DNS
- The destination hostname can only be resolved from within the proxy network
- You're using Tor or similar anonymizing proxies

To revert to local DNS resolution:

bash

git config --global http.proxy socks5://127.0.0.1:1080
git config --global https.proxy socks5://127.0.0.1:1080

5Configure proxy for specific domains only

Instead of a global proxy, you can configure Git to use the proxy only for specific hosts:

bash

# Proxy only for GitHub
git config --global http.https://github.com.proxy socks5h://127.0.0.1:1080

# Proxy only for GitLab
git config --global http.https://gitlab.com.proxy socks5h://127.0.0.1:1080

# Proxy for a corporate Git server
git config --global http.https://git.company.com.proxy socks5h://127.0.0.1:1080

This leaves other Git operations unaffected by proxy settings. To remove domain-specific proxy:

bash

git config --global --unset http.https://github.com.proxy

6Edit .gitconfig directly

You can also manually edit your Git configuration file:

bash

# Open global gitconfig
nano ~/.gitconfig
# Or on Windows: notepad %USERPROFILE%\.gitconfig

Remove or comment out the proxy sections:

ini

# Before (causing the error):
[http]
    proxy = socks5://127.0.0.1:1080
[https]
    proxy = socks5://127.0.0.1:1080

# After (proxy removed):
# [http]
#     proxy = socks5://127.0.0.1:1080
# [https]
#     proxy = socks5://127.0.0.1:1080

Or update with correct settings:

ini

[http]
    proxy = socks5h://127.0.0.1:1080
[https]
    proxy = socks5h://127.0.0.1:1080

7Configure proxy for SSH Git protocol

Note that http.proxy settings only affect HTTPS Git URLs. For SSH URLs ([email protected]:...), you need to configure SSH itself:

bash

# Edit SSH config
nano ~/.ssh/config

Add a ProxyCommand:

bash

Host github.com
    User git
    ProxyCommand nc -X 5 -x 127.0.0.1:1080 %h %p

For Windows or if nc isn't available, you can use connect:

bash

Host github.com
    User git
    ProxyCommand connect -S 127.0.0.1:1080 %h %p

This is necessary when you need to proxy SSH connections, not just HTTPS.

8Update Git to a recent version

Proper SOCKS5 proxy support was added in Git 2.7 (December 2015). If you're running an older version, Git may incorrectly handle SOCKS proxies:

bash

# Check your Git version
git --version

# Update Git
# Ubuntu/Debian
sudo apt update && sudo apt install git

# macOS with Homebrew
brew upgrade git

# Windows: Download from https://git-scm.com/download/win

Git 2.47 (2024) added additional SOCKS5 features like Unix socket support. Consider updating to the latest version for best compatibility.

Advanced notes

### Understanding socks5 vs socks5h

The SOCKS5 protocol supports two modes of operation for DNS resolution:

| Protocol | DNS Resolution | Use Case |
|----------|---------------|----------|
| socks5:// | Local (your machine) | When local DNS works and you only need traffic tunneling |
| socks5h:// | Remote (proxy server) | When DNS must be resolved through the proxy (Tor, restricted networks) |

Using socks5h:// is generally safer when you're unsure, as it ensures all traffic including DNS queries goes through the proxy.

### Proxy Authentication

If your SOCKS5 proxy requires authentication:

bash

git config --global http.proxy socks5h://username:[email protected]:1080

Note: Storing credentials in Git config is insecure. For sensitive environments, consider using a credential helper or environment variables.

### Debugging Proxy Connections

Enable curl verbose mode to see exactly what's happening:

bash

GIT_CURL_VERBOSE=1 git clone https://github.com/user/repo.git

This will show the proxy negotiation process and help identify where the connection fails.

### Common Proxy Software Setup

SSH Dynamic Tunnel:

bash

# Create a SOCKS5 proxy through an SSH server
ssh -D 1080 -f -C -q -N [email protected]

# Then configure Git
git config --global http.proxy socks5h://127.0.0.1:1080

Tor (for anonymity):

bash

# Tor typically runs on port 9050
git config --global http.proxy socks5h://127.0.0.1:9050

# Or Tor Browser on port 9150
git config --global http.proxy socks5h://127.0.0.1:9150

### NO_PROXY Configuration

To exclude certain hosts from proxy:

bash

# Environment variable approach
export no_proxy="localhost,127.0.0.1,.local,.company.com"

# Git doesn't have a native no_proxy config, use domain-specific proxy instead
git config --global http.https://internal.company.com.proxy ""

### Windows-Specific Notes

On Windows, proxy settings can also come from Internet Explorer/Edge settings. Git may pick these up through libcurl. To override:

bash

# Explicitly disable system proxy
git config --global http.proxy ""

### CI/CD Environments

In CI/CD pipelines, proxy settings often come from environment variables set by the runner:

yaml

# GitHub Actions example - clear proxy for direct connection
- name: Clear proxy settings
  run: |
    unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY all_proxy
    git config --global --unset http.proxy || true
    git config --global --unset https.proxy || true

How to fix fatal: unable to access: SOCKS5 connection to proxy failed in Git

What this error means

Typical symptoms

Common causes

How to fix "fatal: unable to access: SOCKS5 connection to proxy failed"

Advanced notes

Related errors

Official resources & further reading