Fix Git 'fatal: couldn't resolve host' in local and CI pipelines

What this error means

Git prints this when it cannot resolve the remote’s hostname to an IP address. Typical root causes:

• DNS outage or misconfiguration
• Wrong remote URL (typo, stale host)
• Proxy/VPN settings interfering with DNS
• Corporate SSL inspection or PAC files
• Container/CI runners lacking proper DNS config
• WSL or system resolver cache issues

Quickstart (most common fixes)

1. Verify the remote URL.
   • git remote -v
   • If wrong, fix: git remote set-url origin https://github.com/owner/repo.git
2. Test DNS resolution of the host.
   • Linux/mac: dig +short github.com or nslookup github.com
   • Windows (PowerShell): Resolve-DnsName github.com
3. Check proxies that can break DNS.
   • env | grep -i proxy
   • git config --global --get http.proxy
   • Temporarily unset: unset http_proxy https_proxy no_proxy; git config --global --unset-all http.proxy; git config --global --unset-all https.proxy
4. Flush/repair resolver.
   • Linux (systemd): sudo resolvectl flush-caches; sudo systemctl restart systemd-resolved
   • macOS: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
   • Windows: ipconfig /flushdns
5. Re-run with verbose curl to see details.
   • GIT_CURL_VERBOSE=1 GIT_TRACE=1 git ls-remote https://github.com

Minimal working example: DNS-and-proxy diag script (Linux/mac)

This script checks URL, DNS, proxy, and basic connectivity for a Git host.

#!/usr/bin/env bash
set -euo pipefail
HOST="${1:-github.com}"
REMOTE="${2:-origin}"

say() { printf "[diag] %s\n" "$*"; }

say "Remote URL (if exists):"
if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  git remote -v | awk 'NR==1{print}' || true
else
  say "Not in a Git repo; skipping remote check"
fi

say "DNS (dig/nslookup/getent):"
(dig +short "$HOST" || true) | sed 's/^/[dig] /'
(nslookup "$HOST" 2>/dev/null | awk '/^Address: /{print}' || true) | sed 's/^/[nslookup] /'
(getent ahosts "$HOST" 2>/dev/null | awk '{print $1}' | sort -u || true) | sed 's/^/[getent] /'

say "Proxy environment:"
env | grep -iE '^(http|https|no)_proxy=' || echo "[none]"

say "Git proxy config:"
(git config --global --get-regexp '^(http|https)\.proxy' || true)

say "HTTP(S) connectivity test with curl:"
HTTP_PROXY="" HTTPS_PROXY="" NO_PROXY="" \
  curl -I --connect-timeout 5 --max-time 10 https://$HOST 2>&1 | sed 's/^/[curl] /'

say "Verbose Git probe:"
GIT_CURL_VERBOSE=1 GIT_TRACE=1 git ls-remote https://$HOST 2>&1 | sed 's/^/[git] /' || true

say "If DNS empty above, check /etc/resolv.conf or resolver service."

Usage:

• Save as git-dns-diag.sh, make executable, then: ./git-dns-diag.sh github.com

Step-by-step troubleshooting

1. Confirm the remote URL and protocol

   • Show remotes: git remote -v
   • Common mistakes: typos (githb.com), wrong protocol (ssh vs https), extra spaces/newlines.
   • Fix: git remote set-url origin https://github.com/owner/repo.git

2. Verify DNS resolution

   • Linux/mac:
     • dig +short your.git.host
     • getent hosts your.git.host
   • Windows (PowerShell): Resolve-DnsName your.git.host
   • If no IPs resolve:
     • Check /etc/resolv.conf (Linux/mac) or network DNS settings.
     • If using systemd-resolved: resolvectl status; ensure DNS servers are set.
     • In containers: pass DNS servers (e.g., docker run --dns 1.1.1.1 --dns 8.8.8.8 ...).

3. Check proxy and VPN

   • Environment variables: http_proxy, https_proxy, NO_PROXY (case-insensitive).
   • Git config proxies: git config --global --get http.proxy
   • Windows WinHTTP proxy: netsh winhttp show proxy
   • Actions:
     • Temporarily disable proxy to test: unset http_proxy https_proxy; git config --global --unset-all http.proxy; netsh winhttp reset proxy
     • Ensure NO_PROXY includes your Git host and its domain (e.g., .github.com) if bypass allowed.
     • Disconnect VPN or captive portal, re-test.

4. Flush and restart DNS components

   • Linux (systemd): sudo resolvectl flush-caches && sudo systemctl restart systemd-resolved
   • Linux (nscd): sudo service nscd restart
   • macOS: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
   • Windows: ipconfig /flushdns

5. WSL-specific

   • If WSL loses DNS after network changes: echo "[network] generateResolvConf = false" | sudo tee -a /etc/wsl.conf; set nameservers in /etc/resolv.conf; wsl.exe --shutdown
   • Alternatively, ensure /etc/resolv.conf is auto-generated and valid.

6. Test with IPv4-only if IPv6 path is broken

   • curl -4 -I https://your.git.host
   • For Git: GIT_CURL_VERBOSE=1 GIT_TRACE=1 git -c http.version=HTTP/1.1 ls-remote https://your.git.host
   • System-wide IPv6 issues can appear as DNS failures if AAAA is returned but unreachable.

7. CI and containers

   • Ensure the runner has DNS configured:
     • Docker: run containers with explicit --dns or configure Docker daemon DNS.
     • Kubernetes: verify cluster DNS (CoreDNS) and set dnsPolicy/dnsConfig on Pods.
   • In ephemeral jobs, proxies may be injected; print env and git config early in the job and adjust NO_PROXY.
   • For self-hosted runners, check local resolvers and corporate proxy/PAC enforcement.

8. Fall back to alternate protocol (temporary)

   • If HTTPS blocked but SSH is allowed: ssh -T [email protected] then set remote URL to SSH.
   • If SSH blocked but HTTPS allowed: use https remote.

Common causes and fixes

Pitfalls

• Editing /etc/hosts with public IPs for cloud Git hosts can break later due to changing IPs.
• Leaving proxy variables set in shell rc files causes sporadic CI/local mismatches.
• Assuming ping success equals HTTPS success; ICMP can be blocked while HTTPS works (and vice versa).
• Hard-coding 8.8.8.8 in corporate networks can violate policy and fail; prefer approved DNS.
• PAC files can override env proxies; WinHTTP and WinINET proxies differ on Windows.

Performance notes

• Stable DNS reduces retries and timeouts. Use reliable resolvers close to your network.
• Avoid unnecessary proxy chaining; each hop adds latency and failure modes.
• Use NO_PROXY to bypass proxies for allowed internal Git hosts to reduce resolution overhead.
• In CI, reuse runner images with known-good resolver config to avoid cold-start DNS issues.
• Minimize repeated Git remote invocations in scripts; batch operations when possible.

Verification checklist

• git remote -v shows the correct host and protocol
• dig/nslookup/Resolve-DnsName return valid IPs for the host
• Proxy variables and Git proxy config are unset or correct
• DNS caches flushed; resolver services healthy
• CI/container runners have DNS servers configured

Tiny FAQ

• Q: Is this a Git bug? A: No. It reports a system/network resolution problem.
• Q: Why does curl work but Git fail? A: Git may use different proxy or certificate settings; check git config and env.
• Q: Do I need admin rights to fix this? A: Often no; you can correct remotes, env, and per-user Git config. Resolver changes may require admin.
• Q: How do I prefer IPv4? A: Use curl -4 and consider system resolver settings; some networks break IPv6 paths.