Attempting to connect to a remote server, cloud instance, or Git repository using the Secure Shell client only to encounter the error: ssh: Could not resolve hostname server.example.com: Name or service not known stops administrative workflows immediately. This error message is generated directly by the OpenSSH client when the operating system’s name service switch (NSS) and DNS resolver fail to translate the provided hostname into an IP address. While a simple typo in the remote server address is common, persistent resolution failures across verified hostnames point to syntax errors in ~/.ssh/config, misconfigured DNS resolvers in /etc/resolv.conf, or invalid character escaping in terminal scripts.
Why OpenSSH Fails to Resolve Remote Hostnames
OpenSSH relies on standard system glibc resolver functions (such as getaddrinfo). The failure occurs when:
- Typographical Errors in Command Syntax: Accidentally omitting spaces between SSH flags and hostnames (e.g., typing
ssh -i key.pemuser@hostinstead ofssh -i key.pem user@host). - Malformed Host Stanzas in ~/.ssh/config: Incorrect indentation, invalid alias names, or missing
HostNamedirectives in your local OpenSSH configuration file. - Unresponsive DNS Nameservers: Local resolver configuration in
/etc/resolv.confpointing to unreachable DNS servers or experiencing systemd-resolved socket failures. - Missing Local Network Host Entries: Connecting to an internal local server using a custom hostname without a corresponding record in
/etc/hostsor local mDNS (Avahi/Bonjour).
Step 1: Check Command Line Syntax and Space Separation
A frequent beginner mistake is concatenating SSH command parameters, causing OpenSSH to parse username flags as part of the destination hostname.
- Examine your command carefully. Notice this common mistake:
# Incorrect: SSH treats "[email protected]" as the argument for the port flag ssh -p [email protected] - Ensure distinct spaces separate all flags, options, and user host combinations:
# Correct syntax: ssh -p 22 [email protected] - If connecting to a Git remote (such as GitHub or GitLab), verify that you did not accidentally prepend
https://to an SSH connection string:# Incorrect: ssh https://github.com # Correct: ssh -T [email protected]
Step 2: Inspect and Correct ~/.ssh/config Directives
If you use an SSH config file to manage aliases, invalid directives will break hostname lookup.
- Open your user SSH configuration file in a text editor:
nano ~/.ssh/config - Ensure each host block follows standard OpenSSH syntax with proper spacing:
Host myserver HostName 192.168.1.50 User ubuntu IdentityFile ~/.ssh/id_rsa Port 22 - Notice that
Hostdefines the friendly alias (used when runningssh myserver), whileHostNamedefines the actual physical IP address or fully qualified domain name. - Save changes (Ctrl + O, Enter) and exit (Ctrl + X).
Step 3: Map Hostnames Locally in /etc/hosts
If connecting to internal development servers, lab Raspberry Pis, or machines without public DNS records, add static mapping to your local hosts file.
- Open the system hosts file with administrative privileges:
sudo nano /etc/hosts - Add an entry pairing the remote server IP address with your desired hostname:
192.168.1.100 dev-server.local dev-server - Save and exit. Test connectivity immediately:
ssh user@dev-server
Step 4: Test and Flush the Local DNS Resolver
If standard internet domains fail to resolve, diagnose and refresh your local DNS configuration.
- Test if your system resolver can query external domains:
getent hosts google.com - If the command returns nothing or times out, check your active nameservers in
/etc/resolv.conf:cat /etc/resolv.conf - On distributions using
systemd-resolved(such as Ubuntu and Debian), restart the resolver daemon and flush caches:sudo resolvectl flush-caches sudo systemctl restart systemd-resolved - If DNS issues persist, add reliable public fallback resolvers (e.g.,
1.1.1.1or8.8.8.8) to your network manager configuration.