MySQL Connection Refused: Step-by-Step Troubleshooting Guide

A comprehensive, well-organized guide to diagnosing and fixing "Connection Refused" errors when connecting to MySQL. Learn systematic troubleshooting to identify your specific problem and implement the right solution.

Table of Contents

1. Introduction
2. Universal Diagnostics
3. Error Codes Reference
4. Problem Categories
5. Local Connection Problems
6. Remote Connection Problems
7. Connection Methods & Tools
8. Conclusion
9. External Resources

Introduction

What is "Connection Refused"?

When you see a "Connection Refused" error, it means your client application tried to connect to MySQL, but the connection was actively rejected. This is different from a timeout or network error—the server is reachable but not accepting the connection attempt.

Who This Affects

• Developers connecting to development databases
• System administrators managing production systems
• DevOps engineers deploying applications
• Database administrators troubleshooting client issues
• Anyone trying to access a remote MySQL database

How to Use This Guide

This guide follows a logical progression:

1. First: Understand what error codes mean
2. Second: Run universal diagnostics to narrow down the problem
3. Third: Identify which problem category applies to you
4. Fourth: Find the solution for your OS
5. Finally: Implement and verify the fix

By the end, you'll understand exactly why the connection failed and how to fix it.

Universal Diagnostics

Before troubleshooting specific issues, run these checks on everyone's first step. These diagnostics work regardless of OS, local/remote setup, or specific configuration.

Check 1: Is MySQL Running?

The most common cause of connection refused is simply that MySQL isn't running.

Linux

# Check service status
systemctl status mysql

You should see active (running). If it shows inactive (dead), MySQL isn't running.

Alternative check:

# Look for MySQL process
ps aux | grep mysqld

This should show a line with /usr/sbin/mysqld or similar. If you only see your grep command, MySQL isn't running.

Windows

Open Services by pressing Win + R, typing services.msc, and pressing Enter. Find MySQL80 (version number may vary). The Status column should show Running and Startup Type should show Automatic.

Or check from Command Prompt (as Administrator):

sc query MySQL80

Look for STATE : 4 RUNNING.

macOS

# Check with Homebrew
brew services list | grep mysql

This should show mysql started. Or check for the process:

ps aux | grep mysqld

If MySQL Isn't Running

Start it immediately:

Linux:

sudo systemctl start mysql
sudo systemctl status mysql

Windows (as Administrator):

net start MySQL80

macOS:

brew services start mysql

Wait 2–3 seconds for MySQL to fully initialize, then try connecting again.

Check 2: Is MySQL Listening on Port?

Even when MySQL is running, it must be actively listening for connections on a port. By default, this is port 3306.

All Platforms – Check Listening Port

Linux/macOS:

netstat -an | grep 3306

Or the modern alternative:

ss -an | grep 3306

Windows:

netstat -an | findstr 3306

What to Look For

tcp        0      0 0.0.0.0:3306            0.0.0.0:*               LISTEN

This means MySQL is listening on port 3306 on all interfaces.

If you see nothing, MySQL isn't listening on port 3306. If you see 127.0.0.1:3306 instead of 0.0.0.0:3306, it is only accepting local connections.

Find Out What Port MySQL Actually Uses

MySQL might be configured for a different port:

Linux/macOS:

grep "^port" /etc/mysql/my.cnf

Or search all config locations:

find /etc /usr/local -name "my.cnf" 2>/dev/null | xargs grep "^port"

Windows:

Look in C:\ProgramData\MySQL\MySQL Server 8.0\my.ini for the port setting.

If MySQL is using port 3307 instead of 3306, use that port in your connection attempts going forward.

Check 3: Can You Reach the Server?

This determines if it's a network or firewall issue versus a server configuration issue.

Local Connection Test

mysql -u root -p -h 127.0.0.1

If this works, MySQL is running and accepting local connections.

Remote Connection Test

mysql -u root -p -h 192.168.1.100

Replace with your actual MySQL server IP.

Understanding the Response

Works immediately → Server reachable and accepting connections.

"Connection refused" instantly → Server reachable but rejecting the connection.

Hangs then times out → Server unreachable due to network or firewall issues.

Error Codes Reference

When MySQL connection fails, the error message includes a code. Understanding these codes reveals the root cause.

Connection-Related Error Codes

Authentication Error Codes

Network Error Codes

Problem Categories

After running diagnostics, identify which category describes your situation. Each has different solutions.

Category 1: Local Connection (localhost)

You're connecting to MySQL on the same machine where it's installed. You should see 127.0.0.1 or localhost in your connection string.

Typical setup:

mysql -u root -p -h localhost
# or
mysql -u root -p -h 127.0.0.1

If this fails: Jump to Local Connection Problems

Category 2: Remote Connection (Different Machine)

You're connecting to MySQL on a different machine using its IP address or hostname. This requires proper network and firewall configuration.

Typical setup:

mysql -u root -p -h 192.168.1.100
# or
mysql -u root -p -h mysql.example.com

If this fails: Jump to Remote Connection Problems

Category 3: SSH Tunnel Setup

You're using SSH tunnels for secure remote access. SSH tunnels encrypt the database connection through SSH.

Typical setup:

ssh -L 3307:localhost:3306 username@server.com
mysql -u root -p -h localhost -P 3307

If this applies: Jump to SSH Tunnel Setup

Local Connection Problems

Local connections use either Unix sockets or TCP to localhost. If remote connections work but local connections do not, the issue is usually related to sockets, ports, or credentials.

Problem: MySQL Not Running (Instant Fix)

Symptoms

• Immediate "Connection refused" error
• systemctl status mysql shows "inactive"
• ps aux | grep mysqld shows no MySQL process

Solution

Start MySQL:

Linux:

sudo systemctl start mysql
sudo systemctl status mysql

Windows (as Administrator):

net start MySQL80

macOS:

brew services start mysql

Wait 2–3 seconds for full initialization, then try connecting again.

If MySQL starts and then immediately stops, check the error log for startup errors:

Linux:

sudo tail -50 /var/log/mysql/error.log

Windows:

Open Event Viewer → Windows Logs → Application, and look for MySQL errors.

macOS:

tail -50 /usr/local/var/log/mysql/error.log

Problem: Wrong Socket Location

Symptoms

• Error: "Can't connect to MySQL server on 'localhost' (2)"
• Socket path shown in error (for example, /var/run/mysqld/mysqld.sock)
• mysql -u root -p fails, but explicit TCP connections may work

Cause

Unix sockets are files MySQL creates for local connections. If the socket path is incorrect or the file does not exist, local connections fail.

Solution

Verify the socket exists:

ls -l /var/run/mysqld/mysqld.sock

If it does not exist, restart MySQL:

sudo systemctl restart mysql

MySQL recreates the socket on startup.

To connect using a non-standard socket location:

mysql -u root -p -S /tmp/mysql.sock

Find the actual socket location in MySQL configuration:

grep "^socket" /etc/mysql/my.cnf

Problem: Wrong Port

Symptoms

• Connection errors even though MySQL is running
• MySQL listening on a different port than expected
• Port 3306 already in use by another application

Solution

Find which port MySQL is actually using:

# Linux/macOS - check config
grep "^port" /etc/mysql/my.cnf

# Windows - check my.ini
findstr /C:"port" "C:\ProgramData\MySQL\MySQL Server 8.0\my.ini"

# Any OS - check what's listening
netstat -an | grep LISTEN | grep mysql

Connect using the correct port:

mysql -u root -p -P 3307

If another application is using port 3306, you can:

• Start MySQL on a different port
• Stop the conflicting application
• Change the conflicting application's port

To Change MySQL Port

Edit the MySQL configuration file:

Linux/macOS:

sudo nano /etc/mysql/my.cnf

In the [mysqld] section, add or modify:

[mysqld]
port = 3307

Windows:

Edit C:\ProgramData\MySQL\MySQL Server 8.0\my.ini using Notepad (as Administrator).

Restart MySQL:

Linux:

sudo systemctl restart mysql

Windows (as Administrator):

net stop MySQL80
net start MySQL80

macOS:

brew services restart mysql

Problem: Wrong Credentials

Symptoms

• Error: "Access denied for user 'root'@'localhost' (using password: YES)"
• Correct password works elsewhere but not locally
• Connection works for one user but not another

Solution: Check If User Exists

Connect as root (if possible):

mysql -u root -p

Then verify the user:

SELECT User, Host FROM mysql.user WHERE User='myuser';

If no rows are returned, the user does not exist.

Solution: Create Missing User

CREATE USER 'myuser'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON *.* TO 'myuser'@'localhost';
FLUSH PRIVILEGES;

Solution: Reset Forgotten Password

If you forgot the root password, restart MySQL without authentication:

Linux:

sudo systemctl stop mysql
sudo /usr/sbin/mysqld_safe --skip-grant-tables &
mysql -u root

Windows:

net stop MySQL80
mysqld --skip-grant-tables

Then in another MySQL client:

FLUSH PRIVILEGES;
ALTER USER 'root'@'localhost' IDENTIFIED BY 'newpassword';
EXIT;

Restart MySQL normally:

Linux:

sudo systemctl restart mysql

Windows (as Administrator):

net stop MySQL80
net start MySQL80

Remote Connection Problems

Remote connections require additional configuration. MySQL must allow remote access, and the firewall must permit it. If local connections work but remote connections do not, follow this section.

Problem: Server Only Accepts Local Connections

Symptoms

• Local connection works
• Remote connection returns "Connection refused"
• Error happens instantly (not a timeout)
• Server responds to ping

Cause

MySQL's bind-address setting defaults to 127.0.0.1, which means it only listens on localhost. Remote connections cannot connect even if the port is open.

Solution: Enable Remote Access

Edit the MySQL configuration file:

Linux/macOS:

sudo nano /etc/mysql/my.cnf

Windows:

Open C:\ProgramData\MySQL\MySQL Server 8.0\my.ini with Notepad (as Administrator).

Find the [mysqld] section and locate:

bind-address = 127.0.0.1

Change it to:

bind-address = 0.0.0.0

Or comment it out:

#bind-address = 127.0.0.1

The value 0.0.0.0 means MySQL will listen on all available network interfaces.

Important: Restart MySQL After Config Change

Configuration changes only apply after restart:

Linux:

sudo systemctl restart mysql

Windows (as Administrator):

net stop MySQL80
net start MySQL80

macOS:

brew services restart mysql

Verify the change:

netstat -an | grep 3306

The output should now show 0.0.0.0:3306 instead of 127.0.0.1:3306.

Problem: Firewall Blocking Connection

Symptoms

• MySQL is running and allows remote access
• Local connections work
• Remote connection times out or is refused
• Server responds to ping

Cause

The server firewall blocks incoming connections on port 3306 while allowing outgoing traffic.

Solution by OS

Linux (UFW):

sudo ufw status
sudo ufw allow 3306/tcp
sudo ufw status

To allow only a specific IP:

sudo ufw allow from 192.168.1.50 to any port 3306 proto tcp

Linux (firewalld):

sudo firewall-cmd --state
sudo firewall-cmd --add-port=3306/tcp --permanent
sudo firewall-cmd --reload
sudo firewall-cmd --list-ports

Windows:

1. Open Windows Defender Firewall
2. Select “Allow an app through firewall”
3. Click “Change settings”
4. Click “Allow another app”
5. Add mysqld.exe

Or via Command Prompt (Administrator):

netsh advfirewall firewall add rule name="MySQL" dir=in action=allow protocol=tcp localport=3306

macOS:

macOS typically does not block local MySQL traffic. If needed, check Firewall Options and allow MySQL.

Verify Port Is Open

Test from a remote machine:

mysql -u root -p -h 192.168.1.100

Or test connectivity:

nc -zv 192.168.1.100 3306

Successful output confirms the firewall is allowing the connection.

Problem: Can't Reach Server (Network Issue)

Symptoms

• Connection hangs then times out
• Error says "Connection timed out"
• Ping fails
• Hostname does not resolve

Cause

The network path between client and server is broken due to incorrect IP, DNS, routing, or upstream firewall rules.

Solution: Test Network Connectivity

ping 192.168.1.100

Possible failures include:

• Wrong IP address
• Server offline
• Routing failure
• ICMP blocked

Solution: Test DNS Resolution

nslookup mysql.example.com
dig mysql.example.com

Windows:

nslookup mysql.example.com

If no IP is returned, DNS is misconfigured.

Solution: Trace Network Route

traceroute 192.168.1.100

Windows:

tracert 192.168.1.100

The hop where the trace stops indicates the network failure point.

Problem: User Not Allowed From Your IP

Symptoms

• Host not allowed error
• Access denied from specific IP
• Server reachable but rejects connection
• User works from another IP

Cause

MySQL users are bound to specific hosts. A user created as 'user'@'localhost' cannot connect remotely.

Solution: Create Remote User

CREATE USER 'remoteuser'@'192.168.1.50' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON *.* TO 'remoteuser'@'192.168.1.50';
FLUSH PRIVILEGES;

To allow connections from any IP:

CREATE USER 'remoteuser'@'%' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON *.* TO 'remoteuser'@'%';
FLUSH PRIVILEGES;

Verify User Was Created

SELECT User, Host FROM mysql.user WHERE User='remoteuser';

Connection Methods & Tools

After fixing the underlying issue, use the right tool for your situation.

Command-Line (mysql client)

The most direct way to test connections.

Basic Syntax

mysql -u username -p -h host -P port -D database

• -u = username
• -p = prompt for password
• -h = hostname or IP
• -P = port (capital P)
• -D = database name

Local Connection Test

mysql -u root -p

Remote Connection Test

mysql -u root -p -h 192.168.1.100

Debug Connection

mysql -u root -p -h 192.168.1.100 -v

The -v flag enables verbose output with detailed error information.

MySQL Workbench (GUI)

Graphical tool for managing MySQL connections.

Create New Connection

1. Open MySQL Workbench
2. Click “New Connection” (+ icon)
3. Enter the following details:

• Connection Name: My Database
• Hostname: 192.168.1.100
• Port: 3306
• Username: root

Click Test Connection.

Interpreting Results

• Success → Connection works correctly
• "Host not found" → Incorrect hostname or IP
• "Access denied" → Invalid credentials
• "Connection timeout" → Server unreachable

phpMyAdmin (Web)

Web-based MySQL administration tool. Configuration is handled through configuration files.

Configure Remote Server

Edit config.inc.php:

$cfg['Servers'][$i]['host'] = '192.168.1.100';
$cfg['Servers'][$i]['user'] = 'root';
$cfg['Servers'][$i]['password'] = 'password';
$cfg['Servers'][$i]['port'] = '3306';

Then access phpMyAdmin and select the configured server from the dropdown menu.

Conclusion

Summary

Connection refused errors follow logical patterns. By systematically checking whether MySQL is running, listening, configured correctly, and reachable, you can identify and resolve nearly all connection issues.

The troubleshooting framework:

1. Diagnose – Run universal checks
2. Categorize – Determine local, remote, or special setup
3. Solve – Apply the appropriate fix
4. Implement – Run OS-specific commands
5. Verify – Confirm the connection works

Prevention Tips

• Keep MySQL running and monitored
• Document ports, users, and allowed IPs
• Test connections after configuration changes
• Review firewall rules regularly
• Secure and audit credentials consistently

When to Get Professional Help

If you've worked through this guide and still can't connect, consider reaching out. Our database services team has resolved thousands of MySQL connection issues and can often identify problems in minutes.

We offer comprehensive database services across MySQL, PostgreSQL, MariaDB, and more — including troubleshooting, optimization, backups, and full database management.

Reach out for a free consultation and let’s discuss how we can support your database needs.

External Resources

Official MySQL Documentation

• MySQL Client Programs
• MySQL Server System Variables
• MySQL User Account Management
• MySQL Network Configuration

SSH & Tunneling

• OpenSSH Client Manual
• SSH Port Forwarding Guide
• PuTTY Documentation

Firewall & Network

• UFW Firewall Guide
• firewalld Documentation
• Windows Firewall Setup