MySQL Error 2003 - Can't Connect to MySQL Server

What It Means

MySQL error 2003 (CR_CONN_HOST_ERROR) means “Can’t connect to MySQL server on ‘hostname’ (error_code).” This error occurs when the MySQL client cannot establish a TCP/IP connection to the MySQL server. The server may not be running, the port may be blocked by a firewall, or the server is not configured to accept TCP connections.

Common Causes

• MySQL server is not running
• Firewall blocking port 3306
• MySQL not configured to listen on the network interface (bind-address)
• Wrong hostname or IP address
• Wrong port number
• Network connectivity issues between client and server
• MySQL max connections limit reached
• Docker networking issues

How to Fix

Verify the server is running and listening

# Check if MySQL is running
sudo systemctl status mysql

# Check if MySQL is listening on the expected port
ss -tlnp | grep 3306
netstat -tlnp | grep 3306

# Test TCP connectivity
telnet hostname 3306
nc -zv hostname 3306

Check MySQL bind-address

# /etc/mysql/mysql.conf.d/mysqld.cnf
[mysqld]
# Default: only accepts local connections
bind-address = 127.0.0.1

# Accept connections from any interface
bind-address = 0.0.0.0

# Accept from specific interface
bind-address = 192.168.1.100

# Restart after changing
sudo systemctl restart mysql

Configure firewall

# UFW (Ubuntu)
sudo ufw allow 3306/tcp

# iptables
sudo iptables -A INPUT -p tcp --dport 3306 -j ACCEPT

# firewalld (CentOS/RHEL)
sudo firewall-cmd --permanent --add-port=3306/tcp
sudo firewall-cmd --reload

# AWS Security Group: Add inbound rule for TCP port 3306

Fix Docker networking

# Docker Compose - ensure services can communicate
services:
  app:
    image: my-app
    depends_on:
      - db
    environment:
      DB_HOST: db      # Use the service name, not localhost
      DB_PORT: 3306

  db:
    image: mysql:8.0
    ports:
      - "3306:3306"    # Expose to host (optional)
    environment:
      MYSQL_ROOT_PASSWORD: rootpass

# Docker: connect from host to container
docker run -p 3306:3306 mysql:8.0
mysql -h 127.0.0.1 -P 3306 -u root -p

Check max connections

-- Check current connections
SHOW STATUS LIKE 'Threads_connected';
SHOW VARIABLES LIKE 'max_connections';

-- Increase if needed
SET GLOBAL max_connections = 500;

-- Make permanent in my.cnf
-- [mysqld]
-- max_connections = 500

Application connection with retry

const mysql = require('mysql2/promise');

async function connectWithRetry(config, retries = 5) {
  for (let i = 0; i < retries; i++) {
    try {
      const connection = await mysql.createConnection(config);
      console.log('Connected to MySQL');
      return connection;
    } catch (error) {
      if (error.code === 'ECONNREFUSED' && i < retries - 1) {
        console.log(`Connection failed. Retrying in ${(i + 1) * 2}s...`);
        await new Promise(r => setTimeout(r, (i + 1) * 2000));
      } else {
        throw error;
      }
    }
  }
}

Related Errors

• MySQL 2002 - Socket connection refused: Similar issue but for Unix socket connections.
• MySQL 1045 - Access denied: Connection succeeded but credentials are wrong.