Fix Git 'Could not resolve host' errors in DevOps and CI

Overview

The Git error:

fatal: unable to access 'https://<host>/<org>/<repo>.git/': Could not resolve host: <host>

means DNS resolution failed for the remote host. This is rarely a Git bug; it’s usually a networking, DNS, proxy, or URL configuration issue.

This guide targets DevOps workflows (local dev, CI, containers, VPN/corporate networks) and focuses on quick, practical fixes.

Quickstart (most cases)

1. Verify the remote URL and host

git remote -v
git config --get remote.origin.url
# Fix typos or wrong scheme
# Example: switch SSH->HTTPS or correct host
# git remote set-url origin https://github.com/<org>/<repo>.git

1. Check DNS resolution

nslookup github.com || dig +short github.com || getent hosts github.com

1. Test connectivity without Git

curl -I --connect-timeout 5 https://github.com/

1. Check and fix proxy configuration

# Environment
env | grep -i _proxy
# Git config
git config --global --get http.proxy
# Clear if stale/misconfigured
git config --global --unset http.proxy || true
git config --global --unset https.proxy || true

1. Flush DNS cache and retry

• Linux (systemd): resolvectl flush-caches
• macOS: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
• Windows (Admin): ipconfig /flushdns

1. Retry with debugging

GIT_TRACE=1 GIT_CURL_VERBOSE=1 git ls-remote origin

Minimal working example

A minimal script that verifies DNS, connectivity, and fetches refs without a full clone.

#!/usr/bin/env bash
set -euo pipefail

# Change to your repo URL if needed
URL="https://github.com/git/git.git"
HOST=$(printf "%s" "$URL" | sed -E 's#https?://([^/]+)/.*#\1#')

echo "Checking DNS for $HOST ..."
if command -v getent >/dev/null 2>&1; then
  getent hosts "$HOST" || { echo "DNS lookup failed"; exit 1; }
elif command -v nslookup >/dev/null 2>&1; then
  nslookup "$HOST" >/dev/null || { echo "DNS lookup failed"; exit 1; }
else
  echo "No DNS tool found (getent/nslookup)."; exit 1
fi

echo "Testing HTTPS connectivity ..."
curl -fsS -I --connect-timeout 5 "https://$HOST/" >/dev/null || { echo "HTTPS connectivity failed"; exit 1; }

echo "Fetching refs via Git (no full clone) ..."
GIT_CURL_VERBOSE=1 git ls-remote "$URL" | head -n 5

echo "Success: DNS and HTTPS to $HOST work and Git can reach the remote."

Run: bash ./mwe.sh. If it fails, follow the steps below that match the failing phase (DNS, HTTPS, or Git).

Step-by-step diagnosis

1. Confirm the remote is correct

• Look for typos, wrong org/repo, or unexpected host (e.g., githb.com).
• Ensure the scheme matches your network policy. Many enterprises allow HTTPS but block SSH.

Fix:

git remote set-url origin https://<correct-host>/<org>/<repo>.git

1. Validate DNS resolution

• Use one or more tools to avoid false negatives.

nslookup <host>
dig +short <host>
getent hosts <host>

If DNS fails:

• On laptops: toggle Wi‑Fi, reconnect VPN, or switch networks.
• In containers: check /etc/resolv.conf contains valid nameserver(s). If empty or wrong, rebuild container with --dns <server> or fix the base image.
• In Kubernetes: ensure the Pod can resolve via cluster DNS (e.g., CoreDNS); exec into the pod and run the commands above.

1. Test network path and TLS outside Git

curl -I --connect-timeout 5 https://<host>/

• Success here but failure in Git often means a Git-level proxy override or SSO page redirection.

1. Inspect proxy configuration

• Environment:

env | grep -i _proxy || true

• Git-level overrides:

git config --global --get http.proxy

• Fixes:
  • If not behind a proxy: unset it (env and Git config).
  • If behind a proxy: set both env and Git config to the correct value.

# Set
git config --global http.proxy http://user:[email protected]:8080
git config --global https.proxy http://user:[email protected]:8080
# Or unset
git config --global --unset http.proxy || true
git config --global --unset https.proxy || true

1. Flush DNS cache See platform commands in the table below. Then retry your Git command.

2. Check VPN/split DNS

• Corporate hosts may only resolve on VPN. Reconnect VPN, ensure DNS split-tunneling is configured, or try from a network that can resolve the host.

1. IPv6 quirks

• Some networks advertise IPv6 but block it. Symptoms: intermittent resolution/connection failures.
• Workarounds:
  • Prefer IPv4 in system resolver (e.g., adjust /etc/gai.conf) or temporarily disable IPv6 at the OS level to test.

1. CI/CD specifics

• Ensure the runner/executor has DNS servers.
• Containers: pin a DNS server or add --dns in Docker. Verify /etc/resolv.conf inside the job.
• Retry strategy for transient DNS: backoff and retry git fetch.

1. Last resort for internal hosts

• Temporarily add a stable IP mapping in /etc/hosts or C:\Windows\System32\drivers\etc\hosts. Keep it temporary and documented.

DNS cache commands by platform

Extra debugging

• Turn on verbose logging when running the failing command:

GIT_TRACE=1 GIT_CURL_VERBOSE=1 git clone https://<host>/<org>/<repo>.git

• Inspect which proxy is used, which IP was resolved, and the exact libcurl error.

Pitfalls

• Proxy set in Git config overrides environment variables and breaks on networks without that proxy.
• Corporate captive portals or SSO pages can intercept HTTPS and break Git.
• Containers inheriting a host’s stale /etc/resolv.conf.
• Wrong remote URL copied from a mirror, or using a deprecated internal hostname.
• Editing /etc/hosts permanently and forgetting to remove it when IPs change.

Performance notes

• Prefer stable, local DNS resolvers. Avoid hardcoding public resolvers in CI unless required.
• DNS negative caching can prolong outages; flushing caches after DNS changes helps.
• Reduce repeated lookups by using connection reuse (Git does this by default) and avoiding unnecessary clean jobs in CI that refetch everything.
• Use shallow clones (--depth 1) to cut retry impact when DNS is flaky but occasionally succeeds.

Tiny FAQ

• Is this a Git bug?
  • Usually no. It indicates the OS/network stack cannot resolve the hostname.
• Why does ping work but Git fails?
  • Ping uses ICMP and may resolve via different rules. Proxies, TLS interception, or split DNS can affect HTTPS uniquely.
• SSH works but HTTPS fails. Why?
  • Different ports, proxies, and certificates apply. Fix your HTTPS proxy/DNS or switch your remote to SSH if allowed.
• How do I see what Git is doing?
  • Use GIT_TRACE=1 GIT_CURL_VERBOSE=1 to print resolver and curl details.
• Is editing hosts safe?
  • Only as a temporary workaround for stable internal hosts. Prefer fixing DNS at the source.