errors/network.spec
SQL Developer Connection Refused — How to Fix
Getting "connection refused" when trying to connect to your database? This guide covers the most common causes and how to fix them.
~/errors/connection-refused.spec
diagnosis
# Error classification
error_class = Network / TCP
layer = transport (before auth)
means = server did not respond on this port
# Common causes
cause_1 = database service not running
cause_2 = firewall / security group blocking port
cause_3 = wrong port number
cause_4 = listener bound to localhost only
time_to_fix = 3 to 10 minutes
difficulty = Intermediate
// run the diagnostic checks below in order
explanation.txt
What "Connection Refused" Means
Understanding the error helps you fix it faster.
A "connection refused" error means SQL Developer tried to connect to your database server, but nothing responded. The server either:
- Isn't running at all
- Is running on a different port
- Is blocked by a firewall
- Is only accepting local connections
This is different from "access denied" (wrong password) or "unknown host" (wrong hostname). Connection refused specifically means the network connection itself failed.
fix/steps
How to Fix It
Try these solutions in order — they go from most common cause to least.
STEP_01
Check if the Database is Running
Windows: press Win+R → type services.msc → Enter. In the Services console, the Name column lists every Windows service. Service names vary by engine + version:
• MySQL 8: MySQL80
• MySQL 5.7: MySQL57
• PostgreSQL 14: postgresql-x64-14
• PostgreSQL 16: postgresql-x64-16
• Oracle XE: OracleServiceXE
• SQL Server: MSSQLSERVER (default) or MSSQL$INSTANCE
The Status column should read "Running". If blank or "Stopped", right-click the service → Start.
Linux/Mac:
sudo systemctl status mysql
sudo systemctl status postgresql
STEP_02
Verify the Port Number
Make sure you're using the correct port in SQL Developer:
MySQL: 3306
PostgreSQL: 5432
Oracle: 1521
SQL Server: 1433
MariaDB: 3306
If your DBA changed the default port, ask them for the correct one.
STEP_03
Check Your Firewall
Firewalls often block database ports by default.
Windows Firewall:
Control Panel → Windows Defender Firewall → Allow an app → Add port exception
Cloud servers (AWS, Azure, GCP):
Check your Security Group / Network Security Group rules.
diagnostics.sh
Test Your Connection
Three diagnostic commands to localize the problem before changing settings.
~/diagnostics/reachability.shbasic ping
# Test if you can reach the server at all
$ ping your-database-server.com
~/diagnostics/port-windows.ps1PowerShell
# Test if the database port is open (Windows)
PS> Test-NetConnection -ComputerName your-server.com -Port 3306
~/diagnostics/port-unix.shmacOS / Linux
# Test if the database port is open (Mac/Linux)
$ nc -zv your-server.com 3306
Interpreting results: If ping works but the port test fails, the database isn't accepting connections on that port (firewall issue or wrong port). If ping itself fails, your hostname or network route is wrong.
PROBLEMS panel
Related Errors
If the symptoms don't match connection refused, one of these guides may help.
Still Having Issues?
If none of these solutions worked, the next step is your database administrator or our support team. They can check server logs and firewall rules that aren't visible from your client.