MySQL Error 2005 occurs when the client cannot resolve or reach the specified MySQL server hostname. This is typically caused by DNS resolution failures, incorrect hostnames, or network connectivity issues.
The MySQL client tried to connect to a server using a hostname, but the client's system (or network) could not determine the IP address of that hostname. This happens at the DNS resolution stage, before the MySQL protocol even starts. The error code 2005 (CR_UNKNOWN_HOST) means the hostname is either misspelled, doesn't exist in DNS, or the client machine cannot reach the DNS server.
Double-check your connection configuration for typos. Common mistakes include:
# Wrong
mysql -h my-sql-server.com -u root -p
# Correct
mysql -h mysql-server.com -u root -pCheck your application's database configuration file or environment variables:
# Check .env or config files
grep DATABASE_HOST .env
grep MYSQL_HOST config.jsEnsure the hostname matches exactly what your MySQL server is configured as.
Test if DNS resolution is the issue by using the IP address directly:
# Using hostname (might fail)
mysql -h db.example.com -u root -p
# Using IP address (test if this works)
mysql -h 192.168.1.100 -u root -pIf IP works but hostname doesn't, your issue is DNS-related. If IP also fails, the problem is network connectivity.
Update your connection string to use the IP:
const connection = {
host: '192.168.1.100', // Instead of 'db.example.com'
user: 'root',
password: 'password',
database: 'mydb'
};Use command-line tools to verify the hostname resolves:
# Test DNS resolution
ping db.example.com
nslookup db.example.com
dig db.example.com
host db.example.comIf these commands fail or show 'unknown host', the hostname doesn't exist or DNS is misconfigured.
On Windows, use:
ipconfig /all # Check DNS settings
ping db.example.com
nslookup db.example.comOn macOS/Linux:
cat /etc/resolv.conf # Check DNS servers
ping db.example.com
dig db.example.comAdd a manual hostname-to-IP mapping to bypass DNS:
# Linux/macOS
sudo nano /etc/hosts
# Add this line:
192.168.1.100 db.example.com
# Windows
Edit: C:\\Windows\\System32\\drivers\\etc\\hosts
Add: 192.168.1.100 db.example.comAfter saving, test the connection:
ping db.example.com
mysql -h db.example.com -u root -pThis is useful for development or when DNS is unavailable, but not a production solution.
Ensure the client can reach the MySQL server's network:
# Test basic connectivity to the host
ping 192.168.1.100
# Test MySQL port specifically
nc -zv db.example.com 3306
# or
telnet db.example.com 3306If these fail:
1. Check server firewall - Allow port 3306:
# Linux firewall
sudo ufw allow 3306/tcp
# iptables
sudo iptables -A INPUT -p tcp --dport 3306 -j ACCEPT2. Check cloud security groups (AWS, Azure, GCP) - Add inbound rule for port 3306
3. Check client-side firewall - Allow outbound connections to port 3306
4. Verify VPN/Network - Ensure you're connected to the correct network if MySQL is behind a VPN
If using Docker and services can't find each other by hostname:
Problem: Default bridge network doesn't support DNS-based service discovery.
Solution: Use a custom network:
# Create a custom network
docker network create myapp-network
# Run MySQL on the network
docker run --name mysql --network myapp-network -e MYSQL_ROOT_PASSWORD=password mysql:8.0
# Run application on same network
docker run --name app --network myapp-network myapp:latest
# Inside app, connect using service name
mysql -h mysql -u root -pAlternatively, use docker-compose which auto-creates networks:
version: '3.8'
services:
mysql:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: password
app:
image: myapp:latest
environment:
DATABASE_HOST: mysql # Service name resolves automaticallyThen connect using the service name (mysql) as the hostname.
If your password contains special characters like @, it can break hostname parsing:
# Wrong - the @ in password breaks parsing
mysql://user:pass@[email protected]/dbname
# Correct - URL-encode the password
mysql://user:pass%[email protected]/dbname
# Or use environment variables
MYSQL_PASSWORD='pass@word123'
mysql -h db.example.com -u user -pFor connection strings in code:
const mysql = require('mysql2/promise');
const connection = await mysql.createConnection({
host: 'db.example.com',
user: 'root',
password: 'pass@word123', // Use object syntax, not URL string
database: 'mydb'
});If direct connection fails but you have SSH access to the MySQL server:
# Create SSH tunnel
ssh -L 3306:localhost:3306 [email protected]
# In another terminal, connect through tunnel
mysql -h 127.0.0.1 -P 3306 -u root -pFor Node.js applications, use the ssh2 library:
const { Client } = require('ssh2');
const mysql = require('mysql2/promise');
const ssh = new Client();
ssh.on('ready', async () => {
ssh.forwardOut(
'127.0.0.1', 3307,
'localhost', 3306,
async (err, stream) => {
if (err) throw err;
const connection = await mysql.createConnection({
stream: stream,
user: 'root',
password: 'password'
});
}
);
});
ssh.connect({
host: 'ssh.example.com',
username: 'user',
privateKey: require('fs').readFileSync('/path/to/key')
});DNS Caching: Some systems cache DNS results. If you changed the DNS record, flush your local DNS cache:
# macOS
sudo dscacheutil -flushcache
# Linux (systemd)
sudo systemctl restart systemd-resolved
# Windows
ipconfig /flushdnsCloud Database Providers: Azure MySQL and AWS RDS often require specific connection formats:
- Azure: [email protected]
- AWS RDS: mydb.xxxxx.us-east-1.rds.amazonaws.com
Ensure you're using the provider's exact hostname format.
IPv6: If your network uses IPv6, make sure the hostname resolves to an IPv6 address if needed. Some clients may not properly handle IPv6 addresses in hostnames.
Connection Pooling: When using connection pools (e.g., HikariCP in Java), the pool may fail to initialize if DNS resolution fails during pool startup. Retry policies and DNS timeout settings affect this behavior.
EE_WRITE (3): Error writing file
How to fix "EE_WRITE (3): Error writing file" in MySQL
CR_PARAMS_NOT_BOUND (2031): No data supplied for parameters
How to fix "CR_PARAMS_NOT_BOUND (2031): No data supplied for parameters" in MySQL
CR_DNS_SRV_LOOKUP_FAILED (2070): DNS SRV lookup failed
How to fix "CR_DNS_SRV_LOOKUP_FAILED (2070): DNS SRV lookup failed" in MySQL
ERROR 1146: Table 'database.table' doesn't exist
How to fix "ERROR 1146: Table doesn't exist" in MySQL
ERROR 1040: Too many connections
How to fix "ERROR 1040: Too many connections" in MySQL