wsl-proxy-fix

name	wsl-proxy-fix
description	Fix WSL git proxy connection errors and configure WSL proxy from Windows host
author	ericyangbit
version	1.1.0
tags	["wsl","git","proxy","networking","troubleshooting","windows"]

WSL Proxy Fix & Configuration Skill

Overview

This skill helps diagnose and fix git proxy connection errors in WSL (Windows Subsystem for Linux) environments, and configure WSL to use Windows host proxy. Common error: "Failed to connect to 127.0.0.1 port 7890 after 0 ms: Connection refused".

Problem Description

When using git in WSL, you may encounter proxy-related connection errors even when no proxy should be active. This happens because:

1. Proxy configurations may be set in git config (global or local)
2. Environment variables may contain proxy settings
3. HTTPS git URLs may fail authentication in WSL
4. Residual proxy settings from Windows may interfere

Quick Start

1. Run the Fix Script

# Make the script executable
chmod +x tools/wsl-proxy-fix.sh

# Diagnose the problem
./tools/wsl-proxy-fix.sh --diagnose

# Auto-fix all issues
./tools/wsl-proxy-fix.sh --auto

# Clean proxy configurations
./tools/wsl-proxy-fix.sh --clean

# Switch to SSH protocol
./tools/wsl-proxy-fix.sh --ssh

# Test GitHub connection
./tools/wsl-proxy-fix.sh --test

2. Manual Fix Commands

If you prefer manual fixes:

# Clear git proxy configurations
git config --global --unset http.proxy
git config --global --unset https.proxy
git config --local --unset http.proxy
git config --local --unset https.proxy

# Clear environment variables
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY all_proxy ALL_PROXY

# Switch from HTTPS to SSH protocol
git remote set-url origin [e-mail]:user/repo.git

# Test connection without proxy
git -c http.proxy= -c https.proxy= push

Detailed Fix Procedures

Scenario 1: "Failed to connect to 127.0.0.1 port 7890"

This error indicates git is trying to use a proxy server at 127.0.0.1:7890, but no proxy is running there.

Solution:

# Clear all proxy configurations
./tools/wsl-proxy-fix.sh --clean

# Or manually:
git config --global --unset http.proxy
git config --global --unset https.proxy
unset http_proxy https_proxy

Scenario 2: "Could not read Username for 'https://github.com'"

This error occurs when using HTTPS URLs without proper authentication.

Solution:

# Switch to SSH protocol
./tools/wsl-proxy-fix.sh --ssh

# Or manually:
git remote set-url origin [e-mail]:user/repo.git

Scenario 3: SSH authentication fails

This happens when SSH keys are not properly configured.

Solution:

# Check SSH keys
ls -la ~/.ssh/

# Test SSH connection
ssh -T [e-mail]

# Generate new SSH key if needed
ssh-keygen -t ed25519 -C "[e-mail]"

Diagnosis Commands

Check what's causing the issue:

# 1. Check git proxy settings
git config --global http.proxy
git config --global https.proxy
git config --local http.proxy
git config --local https.proxy

# 2. Check environment variables
env | grep -i proxy

# 3. Check remote URL
git config --get remote.origin.url

# 4. Test network connectivity
curl -I https://github.com
timeout 10s git ls-remote https://github.com/git/git.git

Common WSL Proxy Issues

Issue 1: Windows Proxy Settings Interference

Windows proxy settings can sometimes leak into WSL.

Fix:

# Add to ~/.bashrc or ~/.zshrc
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY all_proxy ALL_PROXY

Issue 2: Git Credential Manager Issues

Git credential manager may not work properly in WSL.

Fix:

# Use SSH instead of HTTPS
git remote set-url origin [e-mail]:user/repo.git

# Or configure credential helper
git config --global credential.helper store

Issue 3: DNS Resolution Problems

WSL may have DNS issues resolving github.com.

Fix:

# Check DNS resolution
nslookup github.com

# Try using IP directly (temporary)
git config --global url."https://140.82.121.4/".insteadOf "https://github.com/"

Scenario 4: Configure WSL Proxy from Windows Host

This is a common scenario when you run Claude Code (or any CLI) in Git Bash / MINGW64 on Windows and need to configure proxy for a WSL2 distro (e.g., Ubuntu-24.04). The proxy client (e.g., Clash, v2ray) runs on Windows at 127.0.0.1:PORT, and you want WSL to use it.

Key Concepts

WSL2 Networking

• In WSL2, 127.0.0.1 refers to the WSL virtual machine itself, NOT the Windows host
• The Windows host is accessible via:
  • Default gateway: 172.xx.xx.1 (dynamic, changes on reboot)
  • host.docker.internal: Resolves to Windows host IP (available if Docker Desktop is installed)
  • Static IP: You can hardcode the detected IP after finding it once

Finding the Windows Host IP from WSL

# Method 1: Default gateway (WSL2)
ip route | grep default | awk '{print $3}'
# Output: 172.25.48.1

# Method 2: host.docker.internal
getent hosts host.docker.internal
# Output: 192.168.3.2  host.docker.internal

# Method 3: Ping common gateway ranges
ping -c 1 172.25.48.1

The .bashrc Interactive Check Trap

WSL's default .bashrc has this guard at the top:

# If not running interactively, don't do anything
case $- in
    *i*) ;;
      *) return;;
esac

This means when you run wsl -- bash -c 'source ~/.bashrc' (non-interactive), the proxy config is skipped. It only activates in interactive shells (opening the terminal normally). Always use bash -i -c or zsh -i -c for testing.

Automatic Proxy Configuration (Recommended)

Add this to WSL's ~/.bashrc and ~/.zshrc:

# === WSL Proxy Configuration ===
export HOST_IP=172.25.48.1        # Replace with your Windows host IP
export PROXY_PORT=7897            # Replace with your proxy port

proxy_on() {
    export HTTP_PROXY="http://${HOST_IP}:${PROXY_PORT}"
    export HTTPS_PROXY="http://${HOST_IP}:${PROXY_PORT}"
    export http_proxy="${HTTP_PROXY}"
    export https_proxy="${HTTPS_PROXY}"
    export ALL_PROXY="${HTTP_PROXY}"
    export all_proxy="${HTTP_PROXY}"
    export NO_PROXY="localhost,127.0.0.1,::1,*.local,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
    export no_proxy="${NO_PROXY}"
    echo "Proxy ON: ${HTTP_PROXY}"
}

proxy_off() {
    unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy ALL_PROXY all_proxy NO_PROXY no_proxy
    echo "Proxy OFF"
}

proxy_status() {
    if [ -n "${HTTP_PROXY}" ]; then
        echo "Proxy is ON: ${HTTP_PROXY}"
    
         
    
}


proxy_on

Usage:

proxy_on       # Enable proxy
proxy_off      # Disable proxy
proxy_status   # Check proxy status

Also configure Git proxy in WSL:

git config --global http.proxy http://172.25.48.1:7897
git config --global https.proxy http://172.25.48.1:7897

Writing Config to WSL from Windows (Git Bash/MINGW64)

Critical Pitfall: MINGW64 Path Translation

When running commands like wsl.exe -- python3 /mnt/d/path/script.py, MINGW64 automatically converts Unix-style paths to Windows paths, producing corrupted paths like:

/mnt/d/path/script.py → D:/Program Files/Git/mnt/d/path/script.py ❌

Solutions (choose one):

A. Pipe Python script inline (cleanest):

wsl.exe -d Ubuntu-24.04 -- python3 -c "$(cat 'D:/path/to/script.py')"

B. Use base64 encoding (most reliable):

# Encode the config
CONFIG=$(cat << 'EOF'
# your shell config here
export HTTP_PROXY="http://${HOST_IP}:${PROXY_PORT}"
EOF
)
B64=$(echo "$CONFIG" | base64 -w0)

# Clear old config, then decode and append
wsl.exe -d Ubuntu-24.04 -- bash -c "sed -i '/^# === WSL Proxy Configuration ===/,/^# === End Proxy Configuration ===/d' ~/.zshrc"
wsl.exe -d Ubuntu-24.04 -- bash -c "echo \"$B64\" | base64 -d >> ~/.zshrc"

C. Disable MINGW path conversion (per-command):

MSYS2_ENV_CONVERSION=disabled wsl.exe -d Ubuntu-24.04 -- python3 /mnt/d/path/script.py

Complete Setup Script

The --configure-wsl flag of tools/wsl-proxy-fix.sh automates the entire process:

# Auto-detect Windows host IP and configure WSL proxy
./tools/wsl-proxy-fix.sh --configure-wsl

# Configure for a specific WSL distro
./tools/wsl-proxy-fix.sh --configure-wsl --distro Ubuntu-24.04

# Custom proxy port
./tools/wsl-proxy-fix.sh --configure-wsl --port 7890

Common Pitfalls

Pitfall	Symptom	Fix
WSL2 127.0.0.1 != Windows	Can't reach proxy	Use gateway IP or host.docker.internal
.bashrc interactive guard	source ~/.bashrc works but wsl -- bash -c doesn't	Use wsl -- bash -i -c for testing, or normal terminal for daily use
MINGW64 path mangling	wsl.exe python3 /mnt/d/... fails with corrupted path	Use base64 encoding or python3 -c "$(cat ...)"
Shell variable expansion in heredoc	Config file has empty variables	Escape $ (use \$) or use base64 encoding
Proxy set but git push still fails	Git uses its own config, not env vars	Set git config --global http.proxy separately

Preventive Measures

Add these to your shell configuration (~/.bashrc or ~/.zshrc):

# Clear proxy settings on shell startup
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY all_proxy ALL_PROXY 2>/dev/null

# Alias for proxy-free git
alias gitnp='git -c http.proxy= -c https.proxy='

# Function to switch git remote to SSH
git-ssh() {
  local remote_url
  remote_url=$(git config --get remote.origin.url 2>/dev/null)
  if [[ -z "$remote_url" ]]; then
    echo "Error: No remote origin configured"
    return 1
  fi
  
  if [[ "$remote_url" == https://github.com/* ]]; then
    local repo_path="${remote_url#https://github.com/}"
    repo_path="${repo_path%.git}"
    local ssh_url="[e-mail]:${repo_path}.git"
    git remote set-url origin "$ssh_url"
    echo "Switched to SSH: $ssh_url"
  elif [[ "$remote_url" == https://gitlab.com/* ]]; then
    local repo_path="${remote_url#https://gitlab.com/}"
    repo_path="${repo_path%.git}"
    local ssh_url="[e-mail]:${repo_path}.git"
    git remote set-url origin ""
     
  
     
     
  
}

The Fix Script

The tools/wsl-proxy-fix.sh script provides a comprehensive solution:

#!/bin/bash
# WSL Proxy Fix & Configuration Script
# Features:
# 1. Diagnose proxy configurations
# 2. Clean proxy settings
# 3. Switch to SSH protocol
# 4. Test network connectivity
# 5. Auto-fix all issues
# 6. Configure WSL proxy from Windows host (--configure-wsl)

Available options:

• --diagnose: Show all proxy-related configurations
• --clean: Remove proxy settings from git and environment
• --ssh: Convert HTTPS remote URLs to SSH
• --test: Test GitHub connectivity
• --auto: Run all fixes automatically
• --configure-wsl: Configure WSL proxy from Windows host (auto-detect IP, write shell config)
• --configure-wsl --distro <name>: Target a specific WSL distro (e.g., Ubuntu-24.04)
• --configure-wsl --port <port>: Custom proxy port (default: 7897)

Integration with Claude Code

To use this skill with Claude Code:

1. Direct script usage: Claude can run the fix script for you
2. Manual commands: Claude can provide the exact commands needed
3. Diagnosis: Claude can help interpret error messages

Example Claude interaction:

User: "git push fails with proxy error"
Claude: "Run: ./tools/wsl-proxy-fix.sh --diagnose"
Claude: "Then run: ./tools/wsl-proxy-fix.sh --auto"

References

Git Proxy Documentation

• Git Config Documentation
• Git Protocols

WSL Networking

• WSL Networking Overview
• WSL and Proxy Servers

SSH Configuration

• GitHub SSH Setup
• SSH Key Generation

Troubleshooting Guide

If the script doesn't work:

1. Check script permissions:

   chmod +x tools/wsl-proxy-fix.sh
   

2. Run with bash explicitly:

   bash tools/wsl-proxy-fix.sh --diagnose
   

3. Check git version:

   git --version
   

4. Check WSL version:

   wsl --version
   

If SSH still doesn't work:

1. Check SSH agent:

   eval "$(ssh-agent -s)"
   ssh-add ~/.ssh/id_ed25519
   

2. Verify GitHub SSH access:

   ssh -T [e-mail]
   

3. Add SSH key to GitHub:

   cat ~/.ssh/id_ed25519.pub
   # Copy and add to GitHub SSH keys
   

Version History

• v1.1.0 (2026-04-26): Added Windows-to-WSL proxy configuration with MINGW64 path translation handling, base64-safe config transfer, .bashrc interactive guard notes, proxy_on/off/status functions
• v1.0.0 (2026-04-21): Initial release with diagnosis, cleaning, SSH switching, and testing features

License

This skill is provided as-is under MIT License. Use at your own risk.

Support

For issues with this skill:

1. Check the troubleshooting guide above
2. Review the script output for clues
3. Consult WSL and git documentation
4. Ask Claude for help with specific error messages