ConnectionError
requests.exceptions.ConnectionError
Stack trace
requests.exceptions.ConnectionError: HTTPSConnectionPool(host='model-serving.example.com', port=443): Max retries exceeded with url: /predict (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x7f8c4b2d1d30>: Failed to establish a new connection: [Errno 111] Connection refused')) Why it happens
This error occurs when the client tries to send a request to the model serving endpoint but cannot establish a TCP connection. Causes include the server being offline, network misconfiguration, firewall blocking, or DNS resolution failures.
Detection
Monitor connection exceptions in your client code and log connection failures with timestamps and endpoint URLs to detect outages before they impact users.
Causes & fixes
Model serving server is down or crashed
Restart the model serving server and verify it is running and listening on the expected port.
Network firewall or security group blocking access to the endpoint port
Update firewall rules or security groups to allow inbound traffic on the model serving port from your client IPs.
Incorrect endpoint URL or DNS resolution failure
Verify the endpoint URL is correct and that DNS resolves properly from the client environment.
Client-side network issues such as proxy misconfiguration or no internet
Check client network settings, proxies, and connectivity to ensure outbound requests can reach the endpoint.
Code: broken vs fixed
import requests
response = requests.post('https://model-serving.example.com/predict', json={'input': 'data'}) # This line raises ConnectionError
print(response.json())import os
import requests
endpoint = os.environ.get('MODEL_SERVING_ENDPOINT', 'https://model-serving.example.com/predict')
try:
response = requests.post(endpoint, json={'input': 'data'}) # Fixed: use env var and try/except
response.raise_for_status()
print(response.json())
except requests.exceptions.ConnectionError as e:
print(f'Connection failed: {e}') # Handle connection failure gracefullyWorkaround
Wrap the request call in try/except ConnectionError, log the error, and implement a retry with exponential backoff to handle transient network issues.
Prevention
Implement health checks and monitoring on the model serving endpoint, use load balancers with failover, and configure alerts for downtime to prevent prolonged outages.