When configuring or deploying to a server that connects through a network agent, you may see the following error:

```text
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:

```bash
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](/support/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:

```bash
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.access` entries, otherwise deployments will fail intermittently.
- Allow for DNS caching — a change may take up to the record's TTL to take effect.

## Related

- [Deploy to servers in private networks using the DeployHQ Agent](/support/network-agents)
- [Destination address not allowed](/support/destination-address-not-allowed)