ConnectionRefusedError
builtins.ConnectionRefusedError
Stack trace
Traceback (most recent call last):
File "app.py", line 42, in <module>
modal_client.handle_webhook()
File "/usr/local/lib/python3.9/site-packages/modal/client.py", line 210, in handle_webhook
response = requests.post(self.webhook_url, json=payload)
File "/usr/local/lib/python3.9/site-packages/requests/api.py", line 119, in post
return request('post', url, data=data, json=json, **kwargs)
File "/usr/local/lib/python3.9/site-packages/requests/api.py", line 61, in request
return session.request(method=method, url=url, **kwargs)
File "/usr/local/lib/python3.9/site-packages/requests/sessions.py", line 530, in request
resp = self.send(prep, **send_kwargs)
File "/usr/local/lib/python3.9/site-packages/requests/sessions.py", line 643, in send
r = adapter.send(request, **kwargs)
File "/usr/local/lib/python3.9/site-packages/requests/adapters.py", line 439, in send
raise ConnectionRefusedError("Connection refused by the server")
builtins.ConnectionRefusedError: Connection refused by the server Why it happens
This error occurs when Modal tries to send an HTTP request to your webhook endpoint but the connection is refused by the server. This usually means the endpoint URL is incorrect, the server is down, the port is closed, or a firewall is blocking the connection.
Detection
Monitor webhook delivery failures and catch ConnectionRefusedError exceptions in your webhook handler code to log unreachable endpoint URLs before the app crashes.
Causes & fixes
Webhook URL is incorrect or points to a non-listening port
Verify and correct the webhook URL in your Modal configuration to point to a valid, running server and open port.
Local development server is not running or not exposed publicly
Start your local server and use a tunneling tool like ngrok to expose it publicly for Modal to reach.
Firewall or network rules block incoming connections to the webhook endpoint
Configure firewall and network settings to allow inbound HTTP requests on the webhook port.
Modal environment lacks internet access or DNS resolution for the webhook domain
Ensure Modal's execution environment has proper network access and DNS can resolve your webhook domain.
Code: broken vs fixed
import modal
client = modal.Client()
# This will raise ConnectionRefusedError if webhook URL is unreachable
client.handle_webhook() # triggers connection refused errorimport os
import modal
os.environ['MODAL_WEBHOOK_URL'] = 'https://your-public-server.com/webhook' # fixed webhook URL
client = modal.Client(webhook_url=os.environ['MODAL_WEBHOOK_URL'])
# Now the webhook call succeeds if the server is reachable
client.handle_webhook()
print("Webhook handled successfully")Workaround
Wrap the webhook call in try/except ConnectionRefusedError, log the failure, and retry later or alert the dev team to fix the endpoint.
Prevention
Use health checks and monitoring on your webhook server, ensure it is always running and publicly accessible, and validate webhook URLs before deploying Modal functions.