Skip to main content
DevOps Insightsguides & answers

OpenSSH · troubleshooting

ssh: Could not resolve hostname

ssh could not turn the host name into an IP address, so it never got as far as connecting or logging in. Usually a typo, a Host alias in ~/.ssh/config pointing at the wrong HostName, a private name only your VPN or office DNS knows, or no working DNS at all. Check the name for typos first.

Reproduced on OpenSSH 10.3p1, . Where the text says “reproduced”, the behaviour was run on that version, not taken from documentation.

First published

New to this? Read what is actually happening first, then come back to the steps.

On this page · 9 sections

Before you start

  • The exact command, and your ~/.ssh/config if you use host aliases.

Run this first

step 1 of 2
ssh -G HOST | grep '^hostname '

Look for A typo, or a name that only resolves on another network

Shows the exact name ssh will resolve after applying ~/.ssh/config.

Work out which cause you have

A few questions to narrow the list. Every answer ends in a command that confirms or rules the cause out — this cannot see your cluster, so nothing here is a certainty until you have checked.

Narrow it down

0 answered · nothing is sent anywhere

Does nslookup github.com work from the same machine?

Cause space

3 of 3 still possible

  • A typo, or a Host alias with the wrong HostNameCommon
  • An internal name only your VPN or office DNS knowsCommon
  • Name resolution is not working at allOccasional

Nothing ruled out yet. Answer the question above and the branches your answer eliminates will strike through here.

Or diagnose it manually

In this order. The first command usually contains the whole answer.

  1. Step 1

    ssh -G HOST | grep '^hostname '

    Shows the exact name ssh will resolve after applying ~/.ssh/config.

    Look for A typo, or a name that only resolves on another network

  2. Step 2

    getent ahosts HOSTNAME    # Linux; on macOS: dscacheutil -q host -a name HOSTNAME

    Asks the same resolver ssh uses, without ssh. Use the hostname line from ssh -G, not an alias.

    Look for An address, or NXDOMAIN / no answer

Every cause, and how to fix it

Ordered by how often each one turns out to be the answer.

A typo, or a Host alias with the wrong HostName

Common

The name was mistyped, or ~/.ssh/config maps your alias to a HostName that is wrong or outdated.

Confirm

ssh -G HOST | grep -E '^(hostname|user|port) '

The hostname ssh will actually look up

Fix

  • Correct the name, or fix the HostName under that Host block in ~/.ssh/config.

An internal name only your VPN or office DNS knows

Common

Hosts such as db.internal or bastion.corp resolve only through company DNS, which you reach over a VPN or the office network.

Confirm

getent ahosts HOSTNAME    # Linux; on macOS: dscacheutil -q host -a name HOSTNAME

No output: the system's resolver, which ssh uses, does not know the name. HOSTNAME is the hostname line from ssh -G, not an alias

Fix

  • Connect the VPN (or use the network that has the internal DNS), then retry.
  • Or use the address your team documents, through the bastion host the network expects.

Name resolution is not working at all

Occasional

No network, a captive portal, or a container or CI runner with a broken resolver. Every name fails, not just this one; the message often says Temporary failure in name resolution.

Confirm

nslookup github.com

A well-known name also fails

Fix

  • Restore network or DNS on the machine; in a container, check its resolver settings and network mode.

Understanding it properly

Skip this if you are mid-incident — the working part of the page is above. Worth reading afterwards, because understanding the mechanism is what stops the next one.

In plain terms

To connect, ssh first asks the system to look up the address of the name you typed, usually through DNS. This error means the lookup failed: either the name is unknown, or the lookup could not be made at all. Nothing about keys, passwords or the server is involved yet, so the fix is in the name, in your SSH config, or in the network's name lookup.

Words used on this page

Host alias
A short name defined in ~/.ssh/config with Host, whose real address is set by HostName.
DNS resolution
Turning a name such as github.com into an IP address.
ssh -G
Prints the configuration ssh would use for a host, including the HostName it will look up, without connecting.
What is actually happening

Reproduced on OpenSSH 10.3p1 on macOS: ssh: Could not resolve hostname nosuchhost.invalid: nodename nor servname provided, or not known. On the Ubuntu 24.04 production host, OpenSSH 9.6p1 printed the same with Name or service not known; the text after the colon comes from the system's resolver, so it differs by operating system.

With a Host alias whose HostName was misspelled, the error named the misspelled HostName, not the alias, and ssh -G ALIAS printed the hostname line ssh would look up.

Temporary failure in name resolution, another resolver message, usually means DNS itself is unreachable (no network, or a broken resolver in a container), rather than an unknown name.

How to tell this is your problem
WhereWhat you see
Linuxssh: Could not resolve hostname HOST: Name or service not known
macOSssh: Could not resolve hostname HOST: nodename nor servname provided, or not known
git clone, git push over SSHThe same line, followed by fatal: Could not read from remote repository.

How to know it is actually fixed

  • nslookup returns an address for the name, and ssh reaches the authentication step.

Stopping it happening again

  • Keep Host aliases in ~/.ssh/config up to date when servers move, and remove ones you no longer use.

Security considerations

  • Do not fix a lookup failure by pasting an IP from an untrusted source into /etc/hosts; a wrong address sends your connection to someone else. Host key checks are what protect you there, so never disable them to get through.

Sources

Behaviour described here is drawn from official documentation. Where a figure could not be confirmed on an official page it is attributed in the text rather than stated as canonical.

Did this get you to an answer?

No text box on purpose — please do not paste production logs anywhere

Something wrong or out of date? Report it

Where to go next