Could not resolve host (tested)

fatal: unable to access '...': Could not resolve host 'X' means git's network layer could not turn the hostname in your remote URL into an IP address. It is a DNS failure, not an authentication or permission problem. We reproduced it over both https and ssh, compared it to the connection-refused error people confuse it with, and tested the standard fixes.

1. The exact error, measured

Cloning a URL with a hostname that does not resolve, over https:

$ git clone https://no-such-host.invalid/x.git
Cloning into 'x'...
fatal: unable to access 'https://no-such-host.invalid/x.git/': Could not resolve host: no-such-host.invalid

Exit code: 128. The message comes from git's http transport (libcurl under the hood), not from your shell or SSH.

2. Could-not-resolve-host vs. connection-refused: don't confuse them

People often blame "DNS" when the real problem is a closed port or a dead server. We tested both back to back so the wording difference is clear.

"Could not resolve host" = the name lookup itself failed, before git ever tried to open a socket. "Could not connect" / "Connection refused" = the name resolved to an IP, but nothing answered on that IP/port. These need completely different fixes: DNS config for the first, checking the server/firewall/URL for the second.

3. Same failure over SSH looks different

The https transport is git's own (libcurl) and prints "Could not resolve host". The ssh transport shells out to your system's ssh binary, which prints its own wording:

$ git clone git@no-such-host.invalid:x/y.git
Cloning into 'y'...
ssh: Could not resolve hostname no-such-host.invalid: Name or service not known
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

Exit code: 128. Git's own line ("Please make sure you have the correct access rights...") is misleading here — it is git's generic fallback message for any ssh failure, not a real permissions problem. The real cause is one line above it: ssh: Could not resolve hostname. Running the same hostname through plain ssh confirms it's an ssh-level DNS failure, not a git-specific one:

$ ssh git@no-such-host.invalid
ssh: Could not resolve hostname no-such-host.invalid: Name or service not known

For contrast, ssh to a resolvable host with a closed port gives yet another wording, confirming resolution succeeded:

$ git clone ssh://git@127.0.0.1:1/x/y.git
ssh: connect to host 127.0.0.1 port 1: Connection refused
fatal: Could not read from remote repository.

4. Isolate git-specific vs. system-wide DNS failure

Before changing any git setting, check whether DNS is broken system-wide or only inside git. Run these against the same hostname:

All three fail the same way for a genuinely unresolvable name — that means it's a system/network DNS problem, not git. We confirmed the reverse too: getent hosts github.com returned an IP and curl -sS -o /dev/null -w '%{http_code}\n' https://github.com/ returned 200 on this box, so the resolver itself works fine; only the deliberately-invalid name fails. If curl/ping resolve a host fine but git still says "Could not resolve host" for that exact same host, suspect a git-specific proxy or config override (section 5), not system DNS.

Also check /etc/resolv.conf for a sane nameserver line (on this box: nameserver 192.168.1.1 and nameserver 1.1.1.1). An empty or unreachable resolv.conf breaks every tool, not just git.

5. Proxies: a different error, and the most common real cause

If a proxy variable or http.proxy config points at a proxy host that itself doesn't resolve, git's message changes to name the proxy, not the git remote:

$ https_proxy="http://no-such-proxy.invalid:8080" git clone https://github.com/git/git.git
fatal: unable to access 'https://github.com/git/git.git/': Could not resolve proxy: no-such-proxy.invalid

We reproduced the same "Could not resolve proxy" wording whether the bad proxy came from the https_proxy environment variable or from git -c http.proxy=... / git config --global http.proxy. Note the different word: proxy vs. host. If you see "Could not resolve proxy", the fix is the proxy setting, not the remote URL.

When the proxy host resolves but refuses the connection, the message reverts to the same "Failed to connect" / "Could not connect to server" wording as section 2 — we reproduced this by pointing http_proxy at a closed local port.

Per widely reported experience (not measured on this box, since we have no such network to test against): the single most common real-world trigger for "Could not resolve host" is a corporate VPN or proxy that intercepts or blocks DNS for git's traffic while a browser on the same machine resolves fine via a different path (e.g. a browser PAC file or built-in proxy-aware resolver that git does not use). If curl and ping also fail from the same shell, it's not git-specific — it's the network policy, and the usual fix is configuring http.proxy/https_proxy to the VPN's required proxy, or asking network/IT for the correct proxy or DNS settings.

6. ~/.ssh/config Host aliases, tested

If the hostname in your remote URL is wrong or blocked, but you have a different route to the real host, an ssh Host alias can route around it without editing the remote URL. We tested this by pointing an alias at a known-good host:

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

$ git clone git@ghalias:git/git.git
Cloning into 'git'...
Host key verification failed.
fatal: Could not read from remote repository.

Resolution succeeded this time — there is no "Could not resolve hostname" line. It got all the way to SSH host-key verification (which failed only because the test's isolated known_hosts was empty, an unrelated setup detail). That confirms the alias correctly resolved ghalias → github.com before ssh even opened a connection.

7. Fix checklist

• Re-read the exact error. "Could not resolve host" = DNS for the remote. "Could not resolve proxy" = DNS for your proxy setting. "Could not connect" / "Connection refused" = DNS was fine, nothing is listening.
• Check the URL itself: a typo'd hostname resolves to nothing, every time. git remote -v to see what's actually configured.
• Isolate git vs. system: run curl -sS https://<same-host>/ and ping -c1 <same-host>. If those also fail, it's system/network DNS, not git — check /etc/resolv.conf and your network connection.
• If curl/ping work but git doesn't, check for a git-specific override: git config --get http.proxy, git config --get --global http.proxy, and the http_proxy/https_proxy/all_proxy environment variables. Unset or fix a bad one with git config --global --unset http.proxy.
• For ssh remotes, test the transport directly: ssh -T git@<host>. If that alone says "Could not resolve hostname", it's ssh's resolver (same system DNS), not git.
• Still stuck behind a corporate VPN/proxy that only your browser can resolve through? Add a Host alias or ProxyCommand in ~/.ssh/config, or set http.proxy to the proxy IT gives you, so git uses the same path your browser does.

If the remote resolves and connects but git still refuses the request, that's a different problem — see DNS Lookup to inspect records directly, or HTTP Headers to check what a URL actually returns once it is reachable.

Written with AI assistance. Measured on 2026-10-02 with git 2.47.3, curl 8.14.1, OpenSSH_10.0p2 (OpenSSL 3.5.7) and iputils ping 20240905 on Debian 13. All clone/fetch commands run against no-such-host.invalid (an unresolvable name) and 127.0.0.1 on a closed port (connection refused, for contrast). The corporate VPN/proxy claim in section 5 is per common reports, not measured here. PlainHeaders is our extension; git, curl, ssh, ping and ping are free.