Python ConnectionRefusedError — What It Means & How to Fix It

What Does This Error Mean?

A ConnectionRefusedError means your Python code tried to connect to a server (host and port), but the server actively rejected the connection. This almost always means the server is not running, is running on a different port, or a firewall is blocking the connection. The error is not a bug in your Python code — it is a network or server configuration problem.

Affected Models

Python 3.12
Python 3.11
Python 3.10
Python 3.9
Python 3.8

Common Causes

The server application (web server, database, API) is not running at all
The server is running on a different port than the one your code is connecting to
You are using the wrong hostname or IP address
A firewall (Windows Firewall, iptables, cloud security group) is blocking the port
The server started but failed to bind to the port — check server logs
You are trying to connect to localhost but the service is running on a different machine

How to Fix It

Read the error message. It shows the host and port your code tried to connect to. Confirm these match your actual server settings.

Example: 'ConnectionRefusedError: [Errno 111] Connection refused' — check what host:port your code used and whether that server is running.
Check that the server is actually running. For a local server, open a terminal and verify the process is active.

On Windows: check Task Manager or run 'netstat -an | findstr PORT_NUMBER'. On Linux/Mac: run 'lsof -i :PORT_NUMBER' or 'ss -tlnp'.
Verify the port number in your code matches the port the server is configured to use. Off-by-one or typo in port numbers is a very common cause.

Common defaults: HTTP is 80, HTTPS is 443, PostgreSQL is 5432, MySQL is 3306, Redis is 6379, MongoDB is 27017.
Check the hostname. If the server is on the same machine, use 'localhost' or '127.0.0.1'. If it is remote, make sure the IP address or domain name is correct.

A server that only listens on '127.0.0.1' cannot be reached from another machine — it must be configured to listen on '0.0.0.0' for remote connections.
Check whether a firewall is blocking the port. On the server machine, temporarily disable the firewall and try connecting again to rule this out.

If disabling the firewall fixes it, add a specific rule to allow your port rather than leaving the firewall off.
If connecting to a cloud service or remote server, check that the security group or network policy allows inbound traffic on the required port.

Cloud platforms (AWS, Azure, GCP) block all ports by default — you must explicitly open each port in the security group settings.

When to Call a Professional

If the server is managed by your team or organization and you do not have access to restart it or check its logs, contact your system administrator or DevOps team. If you are connecting to a third-party API and consistently get this error, check the provider's status page for outages. For complex network or firewall issues, a network administrator can identify blocked ports quickly.

Frequently Asked Questions

My code worked yesterday — why is it giving ConnectionRefusedError today?

The server it was connecting to is most likely not running right now. Servers can stop due to a reboot, a crash, a failed restart after an update, or someone manually stopping the service. Start the server first, then run your Python code again.

How is ConnectionRefusedError different from a timeout?

A refusal is immediate — the server's operating system replies instantly saying 'nothing is listening on this port'. A timeout happens when there is no reply at all — the connection attempt just waits until it gives up. Refused usually means wrong port or server is down. Timeout usually means wrong IP, firewall dropping packets, or very slow network.

Can I catch ConnectionRefusedError in my code and retry automatically?

Yes — wrap your connection code in a try/except block and catch ConnectionRefusedError (or its parent, ConnectionError). You can add a retry loop with a short sleep between attempts using the 'time.sleep()' function. For production code, consider using a library like 'tenacity' that handles retries with exponential backoff.