ConnectionError
requests.exceptions.ConnectionError
Stack trace
requests.exceptions.ConnectionError: HTTPSConnectionPool(host='api.cerebras.net', port=443): Max retries exceeded with url: /v1/chat/completions (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x7f8c4b2d4d60>: Failed to establish a new connection: [Errno -2] Name or service not known')) Why it happens
This error occurs when the Cerebras OpenAI SDK attempts to connect to an endpoint that is unreachable or incorrectly configured. It often happens if the SDK is used with incompatible OpenAI SDK patterns or environment variables, or if network DNS resolution fails.
Detection
Monitor connection exceptions from the SDK client calls and log full error messages including host and port to detect unreachable endpoints before retrying.
Causes & fixes
Using Cerebras SDK with OpenAI SDK v1+ client patterns without setting the Cerebras-specific endpoint.
Set the Cerebras API base URL explicitly in the client configuration or environment variable to ensure correct endpoint resolution.
Missing or incorrect environment variables for Cerebras API key or endpoint host.
Verify and export the correct CEREBRAS_API_KEY and OPENAI_API_BASE environment variables before running the client.
Network DNS resolution failure or firewall blocking access to Cerebras API endpoint.
Check network connectivity, DNS settings, and firewall rules to allow outbound HTTPS traffic to the Cerebras API host.
Code: broken vs fixed
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(model="cerebras-gpt", messages=[{"role": "user", "content": "Hello"}]) # ConnectionError hereimport os
from openai import OpenAI
os.environ["CEREBRAS_API_KEY"] = os.environ.get("CEREBRAS_API_KEY") # Ensure key is set
os.environ["OPENAI_API_BASE"] = "https://api.cerebras.net/v1" # Set Cerebras endpoint explicitly
client = OpenAI(api_key=os.environ["CEREBRAS_API_KEY"])
response = client.chat.completions.create(model="cerebras-gpt", messages=[{"role": "user", "content": "Hello"}]) # Fixed connection
print(response)Workaround
Catch ConnectionError exceptions, log the error details, and retry the request after a short delay or fallback to a cached response if available.
Prevention
Configure your environment with Cerebras-specific API keys and base URLs before initializing the OpenAI client, and validate network connectivity to the Cerebras endpoint in deployment environments.