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

MySQLINTERMEDIATEHIGH

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

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@[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 -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 [email protected]

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

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

What this error means

Typical symptoms

Common causes

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

Advanced notes

Related errors

Official resources & further reading