Python ConnectionRefusedError – Tutorial with Examples

When trying to establish a network connection through Python, you may encounter errors such as the ConnectionRefusedError. This error typically occurs when your program attempts to connect to a remote server, but the server is unreachable or unavailable for some reason.

What is ConnectionRefusedError in Python?

The ConnectionRefusedError is a type of exception that is raised when a client attempts to connect to a server, but is unable to do so because the server has explicitly refused the connection. This error typically occurs when there is no program running on the specified port on the server, or when the server is not set up to receive connections from the client.

In Python, this error is raised as a subclass of the OSError class, which is itself a subclass of the built-in Exception class. This means that the ConnectionRefusedError inherits many of the same methods and properties as other types of exceptions.

Common Causes of ConnectionRefusedError

There are many reasons why you might encounter a ConnectionRefusedError in your Python code. Some of the most common causes include:

• The server is down or unreachable.
• The port number is incorrect.
• The client and server are not using the same protocol.
• The server is overloaded with requests and unable to handle additional requests.

Examples of ConnectionRefusedError

Let’s take a look at some examples of how the ConnectionRefusedError can be raised in Python.

Example 1: Connection Refused Error When Server is Down

import socket

# Create a socket object
client_socket = socket.socket()

# Define the server address and port
server_address = ('localhost', 8000)

try:
    # Connect to the server
    client_socket.connect(server_address)

    # Send a message to the server
    message = "Hello, server!"
    client_socket.sendall(message.encode())

    # Receive the server's response
    response = client_socket.recv(1024)

    print(response.decode())

except ConnectionRefusedError:
    print("Connection refused. Server is down or unreachable.")
except OSError as e:
    print("Error:", e)

# Close the socket
client_socket.close()

In this example, we are trying to connect to a server on the local machine that is listening on port 8000. If the server is not running, we get a ConnectionRefusedError.

The try-except block catches the ConnectionRefusedError and prints a message indicating that the server is down or unreachable.

Output:

Connection refused. Server is down or unreachable.

Example 2: Connection Refused Error Due to Incorrect Port Number

import socket

# Create a socket object
client_socket = socket.socket()

# Define the server address and port
server_address = ('localhost', 9000)

try:
    # Connect to the server
    client_socket.connect(server_address)

    # Send a message to the server
    message = "Hello, server!"
    client_socket.sendall(message.encode())

    # Receive the server's response
    response = client_socket.recv(1024)

    print(response.decode())

except ConnectionRefusedError:
    print("Connection refused. Check that the server is listening on the correct port.")
except OSError as e:
    print("Error:", e)

# Close the socket
client_socket.close()

In this example, we are trying to connect to a server on the local machine that is listening on port 9000. However, the server is actually listening on port 8000. This causes a ConnectionRefusedError to be raised.

The try-except block catches the ConnectionRefusedError and prints a message indicating that the server is not listening on the correct port.

Output:

Connection refused. Check that the server is listening on the correct port.

Example 3: Connection Refused Error Due to Overloaded Server

import socket
import time

# Create a socket object
client_socket = socket.socket()

# Define the server address and port
server_address = ('localhost', 8000)

try:
    # Connect to the server
    client_socket.connect(server_address)

    # Send a message to the server
    message = "Hello, server!"
    client_socket.sendall(message.encode())

    # Simulate an overload on the server
    time.sleep(5)

    # Receive the server's response
    response = client_socket.recv(1024)

    print(response.decode())

except ConnectionRefusedError:
    print("Connection refused. The server is unable to handle additional requests at this time.")
except OSError as e:
    print("Error:", e)

# Close the socket
client_socket.close()

In this example, we are trying to connect to a server on the local machine that is currently overloaded with requests. We simulate this by adding a delay of 5 seconds after sending the message to the server.

The client attempts to connect to the server and send a message, but the server is unable to handle the request due to being overloaded. This causes a ConnectionRefusedError to be raised.

The try-except block catches the ConnectionRefusedError and prints a message indicating that the server is unable to handle additional requests.

Output:

Connection refused. The server is unable to handle additional requests at this time.

Conclusion

The ConnectionRefusedError is a common error that can occur when trying to establish a network connection through Python. It typically occurs when the server is down or unreachable, the port number is incorrect, or the server is overloaded with requests and unable to handle additional requests.

By understanding the causes of this error and knowing how to handle it when it occurs, you can write more robust and reliable networked applications in Python.