Could not resolve hostname
When configuring or deploying to a server that connects through a network agent, you may see the following error:
Could not resolve hostname
This means the hostname entered in your server's configuration could not be looked up in public DNS.
First, check the simple causes
Before changing anything, rule out:
- A typo in the hostname in your server configuration.
- A DNS record that has been deleted or has expired.
- A name that only resolves over a VPN, or from inside your own network.
You can check how the name looks from outside your network by querying a public resolver:
dig +short your-server.example.com @1.1.1.1
If that returns nothing, DeployHQ will not be able to resolve it either.
Why this happens
When a server is set to connect through a network agent, DeployHQ resolves the hostname on our deployment servers, before the connection is handed over to your agent. Only the resulting IP address is sent to the agent.
The lookup therefore does not happen inside your network. If the hostname only exists in your internal or private DNS — for example db01.internal, or a name served by an internal resolver — our servers have no way to resolve it, and the deployment stops with this error.
This is often surprising, because the machine running the agent can resolve the name perfectly well. The agent is simply never asked to do so.
How to fix it
Use the server's IP address (recommended)
Enter the destination server's IP address in the Hostname field of your server configuration, instead of its name.
If the server you are deploying to is the same machine that runs the agent, use 127.0.0.1.
The address also needs to be permitted in the ~/.deploy/agent.access file on the machine running the agent, otherwise the connection is refused with Destination address not allowed. Each line in that file must begin with an IP address or CIDR range — hostnames are ignored.
After changing agent.access, restart the agent:
network-agent restart
If you are still running the legacy Ruby agent, use deploy-agent restart instead.
If you need to use a name rather than an IP address
You can publish a public DNS record that points at the internal IP address — for example an A record for server.example.com pointing to 10.0.0.5. We resolve the name publicly, obtain the internal address, and hand that to your agent, which connects to it as normal.
Before choosing this route, note the following:
- The record must resolve to an IPv4 address. Destinations reached through an agent are looked up over IPv4 only, so a name that has only an IPv6 (AAAA) record will fail with this same error.
- The address published is private and is not routable from the internet, so the record does not by itself make the server reachable from outside your network. It does, however, publish the name and internal address of that machine in public DNS. If that is not acceptable to you, use the IP address instead.
- Some DNS providers will not accept records that point at private addresses, and some resolvers with DNS-rebinding protection discard them. If either applies to you, use the IP address.
- If you use split-horizon DNS, the public answer is the one we use. Make sure it resolves to the address you want handed to your agent.
- If the name can return more than one address, every address it may return must be covered by your
agent.accessentries, otherwise deployments will fail intermittently. - Allow for DNS caching — a change may take up to the record's TTL to take effect.