🚨 MySQL Error: 'ERROR 2005 (HY000): Unknown MySQL server host' — Cause, Fix, and Troubleshooting Guide

Overview

ERROR 2005 (HY000) is a client-side failure: the MySQL client library could not resolve the hostname you gave it into an IP address:

ERROR 2005 (HY000): Unknown MySQL server host 'db.internal.example.com' (-2)

The number in parentheses is the resolver error (-2 / EAI_NONAME means “name not found”). Nothing reached the server — DNS (or /etc/hosts, or the Kubernetes service name) failed first. It is not an auth or firewall problem; it is name resolution.

Symptoms

• Connection fails instantly with 2005 naming the host string.
• ping/nslookup of the same hostname also fails.
• Works with an IP address but not the hostname.
• Started after a DNS change, a namespace move, or a typo in config.

Common Root Causes

1. Typo or wrong hostname

An extra character, wrong domain suffix, or a copy-paste artifact in --host/DATABASE_URL.

2. DNS record missing or not yet propagated

The A/CNAME record does not exist, was deleted, or the change has not propagated to the client’s resolver.

3. Kubernetes/service-discovery name out of scope

Using a short service name (mysql) from a different namespace; the FQDN (mysql.db.svc.cluster.local) is required.

4. Broken resolver config

A bad /etc/resolv.conf, an unreachable DNS server, or missing /etc/hosts entry.

How to diagnose

Resolve the name independently of MySQL:

getent hosts db.internal.example.com
nslookup db.internal.example.com
dig +short db.internal.example.com

If those fail, the problem is DNS, not MySQL. Test connectivity with a literal IP to confirm the server is reachable once the name resolves:

mysql -h 10.0.4.12 -u app -p

Check resolver configuration:

cat /etc/resolv.conf
cat /etc/hosts

Fixes

Correct the hostname or use the fully qualified name:

mysql -h db.internal.example.com -u app -p
# Kubernetes: use the FQDN across namespaces
mysql -h mysql.db.svc.cluster.local -u app -p

If DNS is genuinely unavailable, add a temporary /etc/hosts entry:

10.0.4.12   db.internal.example.com

Fix the resolver so the whole host resolves names again:

# /etc/resolv.conf
nameserver 10.0.0.10
search internal.example.com

For containers, ensure the pod’s DNS policy and the service actually exist:

kubectl get svc mysql -n db
kubectl exec -it <pod> -- getent hosts mysql.db.svc.cluster.local

What to watch out for

• 2005 never reaches the server — do not chase credentials, grants, or firewalls until the name resolves.
• Hardcoding IPs in /etc/hosts fixes the symptom but drifts when the server IP changes; prefer fixing DNS.
• In Kubernetes, short names only resolve within the same namespace; use the FQDN for cross-namespace access.
• A (-3) / EAI_AGAIN code means a temporary DNS failure (server unreachable), not a missing record — check the resolver’s reachability.

Related

• ERROR 2003: Can’t connect to MySQL server (TCP) — the next failure once the name resolves but the port is unreachable.
• ERROR 2002: Can’t connect through socket — the local-socket connection failure counterpart.
• ERROR 1129: Host is blocked — a host-level rejection that happens after a successful connection attempt.