CI "Could not resolve host" - Fix DNS Failures on Runners

By Kaveh Alemi·Latchkey

The runner could not turn a hostname into an IP address. DNS resolution failed before any connection was even attempted - usually a transient resolver hiccup that succeeds on retry.

What this error means

A clone, download, or API call fails immediately with Could not resolve host. Nothing connected because the name never resolved. The same workflow typically passes on a re-run with no change.

CI log

curl: (6) Could not resolve host: github.com
# or
fatal: unable to access 'https://github.com/...': Could not resolve host: github.com

Common causes

Transient DNS resolver blip

The runner’s upstream resolver briefly failed or timed out. DNS is best-effort UDP, so a momentary blip yields a hard "could not resolve" that clears on retry.

Missing or broken resolver configuration

A container with an empty or wrong /etc/resolv.conf, or a runner whose DNS settings were not propagated, cannot resolve any name.

How to fix it

Confirm DNS is working

Test resolution directly and check the resolver config.

Terminal

getent hosts github.com || nslookup github.com
cat /etc/resolv.conf

Retry, then fix config if it persists

Re-run the step - a one-off resolver blip clears on retry.
If it persists, set a working nameserver in /etc/resolv.conf (e.g. nameserver 1.1.1.1).
For containers, pass an explicit DNS server (--dns) or fix the daemon DNS config.

How to prevent it

Wrap network steps in a bounded retry with backoff.
Ensure runners/containers ship a valid resolver config.
Cache or mirror dependencies to reduce external DNS lookups.

Frequently asked questions

What causes ""Could not resolve host""?