[Fixed] ssh: Could not resolve hostname: Name or service not known: Step-by-Step Troubleshooting Guide

Quick Summary: The error ssh: Could not resolve hostname <hostname>: Name or service not known occurs when the OpenSSH client fails to translate a target host string into an IP address. Common root causes include typographical errors or hidden trailing whitespace in SSH commands, malformed host definitions in ~/.ssh/config, missing local mappings in /etc/hosts, or misconfigured DNS resolvers in /etc/resolv.conf.

Understanding the Root Causes

When you initiate an SSH session, the client queries system name service switches (NSS) and local configuration files before attempting a TCP connection on port 22. If name resolution returns no valid A or AAAA records, the OpenSSH connection terminates before packet transmission begins. The primary causes are:

Syntax Errors or Hidden Characters: Passing invisible trailing newlines, non-breaking spaces, or command typos (such as copying host strings from rich text documents or bash environment variables).
Misconfigured SSH Client Aliases: Missing or incorrect HostName directives in your local ~/.ssh/config file.
Unreachable or Misconfigured DNS: Corrupted DNS cache, non-functional nameservers in /etc/resolv.conf, or inactive systemd-resolved services.
Missing Local Intranet Resolution: Private server names that lack entries in /etc/hosts or private DNS zones.

Step 1: Quick Fix – Inspect Syntax and Command Input

Ensure that the target host string does not include hidden characters, malformed environment variables, or unintended colon delimiters (often accidentally copied from SCP or Rsync commands):

# Incorrect syntax example (SCP syntax used with standard SSH)
ssh user@example.com:22

# Correct SSH syntax specifying the port flag explicitly
ssh -p 22 user@example.com

# Strip hidden whitespace when expanding environment variables
TARGET_HOST=$(echo "$REMOTE_HOST" | xargs)
ssh user@"$TARGET_HOST"

Step 2: Fix Configuration in ~/.ssh/config and /etc/hosts

If you connect using host aliases, verify that the alias correctly points to a valid IP address or fully qualified domain name (FQDN) in ~/.ssh/config:

# Edit your user SSH client configuration
nano ~/.ssh/config

# Add or update the target host block:
Host dev-server
    HostName 192.168.1.100
    User ubuntu
    Port 22
    IdentityFile ~/.ssh/id_rsa

For private environments without internal DNS, map the hostname directly to the target IP address in your local /etc/hosts file:

# Add private hostname mapping
sudo tee -a /etc/hosts <<EOF
192.168.1.100 dev-server.local dev-server
EOF

Step 3: Resolve System DNS and Resolver Issues

If the target is a public domain or managed cloud endpoint, test and repair system-level name resolution:

# Check system name resolution directly
getent hosts example.com

# Inspect active nameservers in /etc/resolv.conf
cat /etc/resolv.conf

# If using systemd-resolved, flush and restart the resolver cache
sudo resolvectl flush-caches
sudo systemctl restart systemd-resolved

# Test DNS query using dig or nslookup
dig +short example.com @8.8.8.8

Verification & Testing Steps

Run the SSH client in verbose mode to verify which stage of connection and name resolution succeeds:

# Run SSH with detailed debug logging
ssh -vvv dev-server

# Verify successful host resolution output
# Expected debug output should show:
# debug1: Connecting to 192.168.1.100 [192.168.1.100] port 22.
# debug1: Connection established.

Troubleshooting Summary Comparison

Issue Category	Primary Root Cause	Recommended Fix
Command Syntax	Hidden whitespace or colon port notation	Sanitize input string; use `-p <port>` flag
SSH Config Alias	Missing or misspelled `HostName` directive	Update `~/.ssh/config` with correct IP/FQDN
Local Resolution	Hostname unresolvable in local LAN	Add static IP entry in `/etc/hosts`
System DNS	Unreachable nameserver or stale cache	Flush DNS cache and inspect `/etc/resolv.conf`