ConnectionRefusedError
builtins.ConnectionRefusedError
Stack trace
Traceback (most recent call last):
File "app.py", line 15, in <module>
response = client.chat.completions.create(model="gpt-4o-mini", messages=messages)
File "/usr/local/lib/python3.9/site-packages/openai/api_resources/chat_completion.py", line 30, in create
return super().create(*args, **kwargs)
File "/usr/local/lib/python3.9/site-packages/openai/api_resource.py", line 120, in create
response = self._request("post", url, params)
File "/usr/local/lib/python3.9/site-packages/openai/api_resource.py", line 98, in _request
resp = self._client.request(method, url, params)
File "/usr/local/lib/python3.9/site-packages/openai/api_client.py", line 75, in request
raise ConnectionRefusedError("Connection refused to Azure OpenAI endpoint")
builtins.ConnectionRefusedError: Connection refused to Azure OpenAI endpoint Why it happens
This error occurs when your Python client tries to connect to an Azure OpenAI private endpoint but the connection is refused by the server. Common root causes include incorrect private endpoint DNS configuration, missing virtual network peering, firewall rules blocking traffic, or the private endpoint not being properly set up in Azure.
Detection
Monitor connection exceptions in your client logs for ConnectionRefusedError and verify network connectivity to the Azure private endpoint IP or DNS before making API calls.
Causes & fixes
Private endpoint DNS name is not resolving to the private IP address
Configure your DNS to resolve the Azure OpenAI private endpoint hostname to the private IP address assigned by Azure, typically by setting up a private DNS zone linked to your virtual network.
Virtual network peering or subnet configuration missing or incorrect
Ensure your client VM or service is in a virtual network peered with the Azure OpenAI private endpoint subnet, and that network security groups allow outbound traffic on required ports.
Firewall or NSG rules blocking outbound traffic to the private endpoint
Update firewall and network security group rules to allow outbound HTTPS (port 443) traffic to the private endpoint IP address.
Azure OpenAI private endpoint resource is not properly provisioned or approved
Verify the private endpoint connection status in the Azure portal and approve any pending connections to enable traffic.
Code: broken vs fixed
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["AZURE_OPENAI_API_KEY"],
api_base="https://my-azure-openai.openai.azure.com/",
api_type="azure",
api_version="2023-05-15"
)
messages = [{"role": "user", "content": "Hello"}]
# This line triggers ConnectionRefusedError if private endpoint is misconfigured
response = client.chat.completions.create(model="gpt-4o-mini", messages=messages)
print(response.choices[0].message.content)import os
from openai import OpenAI
# Fix: Ensure DNS resolves private endpoint hostname to private IP
# and network allows connection
client = OpenAI(
api_key=os.environ["AZURE_OPENAI_API_KEY"],
api_base="https://my-azure-openai.openai.azure.com/",
api_type="azure",
api_version="2023-05-15"
)
messages = [{"role": "user", "content": "Hello"}]
response = client.chat.completions.create(model="gpt-4o-mini", messages=messages) # Fixed connection
print(response.choices[0].message.content)Workaround
Temporarily bypass the private endpoint by using the public Azure OpenAI endpoint with proper authentication until network and DNS issues are resolved.
Prevention
Set up Azure Private DNS zones linked to your virtual network for automatic private endpoint DNS resolution and validate network security group and firewall rules during deployment.