How to fix CR_UNKNOWN_HOST (2005): Unknown MySQL server host in MySQL

MySQLINTERMEDIATEHIGHUpdated Dec 29, 2025· 140 views

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.

Quick fix

Fixes CR_UNKNOWN_HOST (2005): Unknown MySQL server host

# Wrong
mysql -h my-sql-server.com -u root -p

# Correct
mysql -h mysql-server.com -u root -p
  1. Verify the hostname spelling
  2. Try connecting with IP address instead of hostname
  3. Test DNS resolution
  4. Check /etc/hosts file for local resolution
mysql — error
# Wrong
mysql -h my-sql-server.com -u root -p
# Correct
mysql -h mysql-server.com -u root -p
CR_UNKNOWN_HOST (2005): Unknown MySQL server host

What this error means

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.

Typical symptoms

  • Connection attempts fail with 'Unknown MySQL server host' message
  • Works with IP address but not with hostname
  • Works on one machine but not another
  • Docker container cannot reach linked or networked MySQL service
  • Cloud database connection fails while local MySQL works
  • Error includes hostname or IP in the error message

Common causes

  1. Hostname is misspelled or incorrect in the connection string
  2. DNS resolver cannot find the hostname (DNS failure or host does not exist)
  3. Network connectivity issue between client and DNS server
  4. Firewall blocking DNS queries (port 53) or MySQL port (3306)
  5. MySQL server is down or unreachable at the specified address
  6. Wrong protocol prefix in connection string (e.g., 'http://' instead of omitting it)
  7. Docker container using default bridge network instead of custom network for inter-container DNS
  8. Connection string password contains special characters that break hostname parsing

How to fix "CR_UNKNOWN_HOST (2005): Unknown MySQL server host"

1Verify the hostname spelling

Double-check your connection configuration for typos. Common mistakes include:

bash
# Wrong
mysql -h my-sql-server.com -u root -p

# Correct
mysql -h mysql-server.com -u root -p

Check your application's database configuration file or environment variables:

bash
# Check .env or config files
grep DATABASE_HOST .env
grep MYSQL_HOST config.js

Ensure the hostname matches exactly what your MySQL server is configured as.

2Try connecting with IP address instead of hostname

Test if DNS resolution is the issue by using the IP address directly:

bash
# 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 -p

If 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:

javascript
const connection = {
  host: '192.168.1.100',  // Instead of 'db.example.com'
  user: 'root',
  password: 'password',
  database: 'mydb'
};
3Test DNS resolution

Use command-line tools to verify the hostname resolves:

bash
# Test DNS resolution
ping db.example.com
nslookup db.example.com
dig db.example.com
host db.example.com

If these commands fail or show 'unknown host', the hostname doesn't exist or DNS is misconfigured.

On Windows, use:

bash
ipconfig /all          # Check DNS settings
ping db.example.com
nslookup db.example.com

On macOS/Linux:

bash
cat /etc/resolv.conf   # Check DNS servers
ping db.example.com
dig db.example.com
4Check /etc/hosts file for local resolution

Add a manual hostname-to-IP mapping to bypass DNS:

bash
# 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.com

After saving, test the connection:

bash
ping db.example.com
mysql -h db.example.com -u root -p

This is useful for development or when DNS is unavailable, but not a production solution.

5Verify network connectivity and firewall

Ensure the client can reach the MySQL server's network:

bash
# 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 3306

If these fail:

1. Check server firewall - Allow port 3306:

bash
# Linux firewall
   sudo ufw allow 3306/tcp
   
   # iptables
   sudo iptables -A INPUT -p tcp --dport 3306 -j ACCEPT

2. 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

6Fix Docker networking issues

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:

bash
# 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 -p

Alternatively, use docker-compose which auto-creates networks:

yaml
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 automatically

Then connect using the service name (mysql) as the hostname.

7Check for special characters in connection strings

If your password contains special characters like @, it can break hostname parsing:

bash
# Wrong - the @ in password breaks parsing
mysql://user:pass@word123@db.example.com/dbname

# Correct - URL-encode the password
mysql://user:pass%40word123@db.example.com/dbname

# Or use environment variables
MYSQL_PASSWORD='pass@word123'
mysql -h db.example.com -u user -p

For connection strings in code:

javascript
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'
});
8Use SSH tunneling as a workaround

If direct connection fails but you have SSH access to the MySQL server:

bash
# Create SSH tunnel
ssh -L 3306:localhost:3306 user@ssh.example.com

# In another terminal, connect through tunnel
mysql -h 127.0.0.1 -P 3306 -u root -p

For Node.js applications, use the ssh2 library:

javascript
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')
});

Advanced notes

DNS Caching: Some systems cache DNS results. If you changed the DNS record, flush your local DNS cache:

bash
# macOS
sudo dscacheutil -flushcache

# Linux (systemd)
sudo systemctl restart systemd-resolved

# Windows
ipconfig /flushdns

Cloud Database Providers: Azure MySQL and AWS RDS often require specific connection formats:
- Azure: user@servername.mysql.database.azure.com
- 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.

Frequently asked questions

What does "CR_UNKNOWN_HOST (2005): Unknown MySQL server host" mean?
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.
How do I fix "CR_UNKNOWN_HOST (2005): Unknown MySQL server host"?
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.
What causes "CR_UNKNOWN_HOST (2005): Unknown MySQL server host"?
Hostname is misspelled or incorrect in the connection string DNS resolver cannot find the hostname (DNS failure or host does not exist) Network connectivity issue between client and DNS server
Is the "CR_UNKNOWN_HOST (2005): Unknown MySQL server host" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading