DNS resolution failure

What this failure means

The runner could not resolve a hostname to an IP address, so the network call failed before it could connect.

Symptoms

Faultline looks for one or more of these log fragments:

no such host
temporary failure in name resolution
name or service not known
getaddrinfo enotfound
dial tcp: lookup
could not resolve host
nodename nor servname provided

Diagnosis

The runner could not resolve a hostname to an IP address, so the network call failed before it could connect.

Fix steps

1. Verify the hostname in the failing command or configuration for typos.

2. Manually resolve the host from inside the CI environment to confirm it is reachable:

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

   If DNS resolution works from the runner but the job still fails, the hostname may be coming from a misconfigured secret or environment variable.

3. Check whether the hostname is internal-only and requires VPN, VPC DNS, or a private resolver. CI runners on cloud providers may not have access to private DNS zones by default.

4. Retry the job once to rule out a transient resolver outage.

5. If the hostname comes from configuration, print the resolved value in the same job or container and confirm it matches the expected environment or secret before retrying.

Validation

• dig +short <hostname> or nslookup <hostname> — confirm successful resolution from the runner before re-running the job.
• Re-run the failing step and confirm the DNS lookup no longer fails.

Why it matters

DNS failures can come from typos in hostnames, transient resolver outages, missing private DNS configuration, or network policies that block access to the resolver.

Prevention

• Keep service endpoints centralized in configuration rather than duplicated across workflows.
• Add environment-specific connectivity checks for critical internal hosts.
• Monitor resolver health on persistent runners or clusters.
• Document which internal domains require private DNS so new runners are provisioned with the correct resolver settings.

Try it locally

getent hosts <hostname>
nslookup <hostname>
getent hosts <hostname>

How Faultline detects it

Use faultline explain dns-resolution to see the full playbook.

faultline analyze build.log
faultline explain dns-resolution

Generated from playbooks/bundled/log/network/dns-resolution.yaml. Do not edit directly.