ConnectionError
Python Programming Language
Severity: ModerateWhat Does This Error Mean?
A ConnectionError means Python tried to connect to a network address — like a website, an API, or a server — and the connection failed. This can happen because the server is down, the address is wrong, there is no internet connection, or a firewall is blocking access. This error comes from the socket and networking layer below Python.
Affected Models
- Python 3.x
- Python 2.x
- All Python versions when using networking
Common Causes
- No internet connection — your computer cannot reach the outside network
- The server or URL is wrong, misspelled, or no longer exists
- The remote server is down or temporarily unavailable
- A firewall or security software is blocking the connection
- The port number is wrong — the server is listening on a different port than you specified
How to Fix It
-
Check your internet connection first. Try opening the same URL in a web browser. If the browser cannot reach it either, the problem is connectivity, not your code.
Ping the server with ping hostname in your terminal to test basic connectivity.
-
Verify the URL or hostname in your code is correct. Copy and paste it into a browser to confirm it works. Even one character wrong will cause a connection failure.
Also check the protocol — make sure you are using https:// if the server requires HTTPS.
-
Add retry logic to your code. Network errors are often temporary. Use the requests library's built-in retry adapter or wrap your request in a try/except with a loop.
Example using the requests library: from requests.adapters import HTTPAdapter; session.mount('https://', HTTPAdapter(max_retries=3))
-
Check if a firewall, VPN, or proxy is interfering. Corporate networks often block outgoing connections to certain ports or addresses. Try on a different network.
If your code works at home but not at work, a corporate firewall is likely the cause.
-
Make sure the port number is correct if you are connecting to a specific port. Common ports: HTTP is 80, HTTPS is 443, databases often use 3306 (MySQL) or 5432 (PostgreSQL).
Use a tool like Telnet or nc to test if a specific port is open: nc -zv hostname port
When to Call a Professional
Most ConnectionErrors can be fixed without professional help. Start by checking your internet connection and verifying the URL is correct. If your code runs fine on one machine but fails on another, suspect a firewall or network policy difference.
Frequently Asked Questions
What is the difference between ConnectionError and TimeoutError?
A ConnectionError means the connection could not be established at all — the server refused or was unreachable. A TimeoutError means the connection started but the server took too long to respond. ConnectionError is like calling a phone that does not ring. TimeoutError is like calling a phone that rings but nobody answers.
How do I make my code handle ConnectionError gracefully?
Wrap your network code in a try/except block and catch ConnectionError. Inside the except block, you can log the error, show a friendly message, wait a moment, and retry. Always plan for the network being unavailable — it will happen eventually.
Does ConnectionError cover all network errors in Python?
ConnectionError is a parent class that covers several related errors, including ConnectionRefusedError, ConnectionResetError, and ConnectionAbortedError. You can catch ConnectionError to handle all of them, or catch the specific subclass if you need to handle them differently.