WebSocket Connection Fails on Azure Python Web App (No Response Headers)

Question

WebSocket Connection Fails on Azure Python Web App (No Response Headers)

Prasanna Sai Kommineni 40

Hello Azure Support,

I am experiencing an issue with WebSocket connections on my Python-based Azure Web App (Linux App Service). Despite configuring the app correctly, the WebSocket connection fails during the handshake phase — the browser reports that the server is not sending response headers, and the connection status shows as "finished" in the Network tab.

Environment Details:

App Service OS: Linux
Runtime Stack: Python 3.x
Framework: FastAPI
**Startup Command:**gunicorn -w 1 -k uvicorn.workers.UvicornWorker main:app --timeout 240
WebSocket Route: /ws
Frontend Connection Code: const ws = new WebSocket("wss://" + location.host + "/ws");

Troubleshooting Steps Taken:

Verified that the WebSocket route is correctly defined in FastAPI.
Reduced Gunicorn workers to 1 to avoid concurrency issues.
Confirmed that the WebSocket URL and protocol (wss://) are correct.
Enabled logging and checked Log Stream — no clear errors, but no response headers are sent during the handshake.
Tested locally with Uvicorn — WebSocket works as expected.

Issue:

On Azure, the WebSocket connection fails silently. The server does not respond with headers, and the connection is closed immediately. This suggests the upgrade request is not reaching the app or is being blocked by the platform’s reverse proxy.

Request:

Could you please help investigate why the WebSocket upgrade request is not being handled properly on this Linux-based Python Web App? Is there any additional configuration or workaround required to support WebSockets in this environment?

Thank you for your assistance.

Hello Azure Support,

I am experiencing an issue with WebSocket connections on my Python-based Azure Web App (Linux App Service). Despite configuring the app correctly, the WebSocket connection fails during the handshake phase — the browser reports that the server is not sending response headers, and the connection status shows as "finished" in the Network tab.

Environment Details:

App Service OS: Linux
Runtime Stack: Python 3.x
Framework: FastAPI
Startup Command:
WebSocket Route: /ws
**Frontend Connection Code:**gunicorn -w 1 -k uvicorn.workers.UvicornWorker main:app --timeout 240

Bhargavi Naragani 7,940 Reputation points Moderator

2025-06-30T04:11:26.0266667+00:00
Hi Prasanna Sai Kommineni,

This behavior is typically due to WebSocket support not being enabled at the App Service level, or a misconfiguration that prevents WebSocket upgrade requests from being forwarded correctly.

To resolve the issue, please ensure the following steps are implemented:

By default, WebSockets are disabled in Azure App Services. You need to explicitly enable them in the Azure Portal: Enable WebSockets in Azure App Service

Your current startup command is mostly correct:
gunicorn -w 1 -k uvicorn.workers.UvicornWorker main:app --timeout 240
However, consider explicitly binding to 0.0.0.0 and port 8000 (or the $PORT environment variable) to be more explicit, especially in containerized environments:
gunicorn -w 1 -k uvicorn.workers.UvicornWorker main:app -b 0.0.0.0:8000 --timeout 240
Or, if using App Service default settings:
gunicorn -w 1 -k uvicorn.workers.UvicornWorker main:app -b 0.0.0.0:$PORT --timeout 240

Azure App Service uses IIS or nginx as a front-end reverse proxy. WebSockets require the correct Upgrade and Connection headers to pass through. While App Service handles this internally when WebSockets are enabled, make sure:

You are not overriding or blocking these headers in middleware.

You're not using HTTPS redirection or security headers that might interfere (e.g., CSP, CORS) without proper configuration. WebSockets and Azure App Service (General Overview)

Sometimes Azure Linux App Services can restrict long-lived connections via front-end gateway behaviors. Make sure you're not using:

ARR Affinity disabled (which could break sticky sessions if needed).

An App Gateway or Azure Front Door configuration that doesn't support WebSockets.

If you're behind Azure Application Gateway, ensure you enable WebSocket support explicitly in the HTTP settings. Enable WebSocket in Application Gateway

Azure Log Stream might not show everything by default. You can use Diagnostic Logs or enable Application Logging to capture errors during connection attempts. Also consider adding logging to your /ws FastAPI endpoint to confirm whether the request is received at all.

Hope this helps, if you have any further concerns or queries, please feel free to reach out to us.
Bhargavi Naragani 7,940 Reputation points Moderator

2025-07-01T04:48:01.67+00:00
Hi Prasanna Sai Kommineni,

Since the WebSocket handshake itself is failing and you're not even seeing headers in the response that strongly points to the handshake not reaching the app container, possibly due to a platform-level restriction, routing misconfiguration, or port/protocol mismatch.

Azure provides a tested example for this exact scenario. It includes both the WebSocket route and correct configuration for Linux App Service:

Use this template: “How to use websockets with FastAPI in App Service” from Azure’s GitHub repo, it covers:

A working /ws endpoint

Correct requirements.txt (fastapi, uvicorn, gunicorn)

Startup command:
gunicorn -w 1 \ -k uvicorn.workers.UvicornWorker \ main:app \ --bind 0.0.0.0:$PORT

Note: $PORT is injected automatically in Linux App Service

Next step: Clone this repo, deploy it unchanged, and test the WebSocket connect.

Verify App Service Linux defaults

Linux App Service has WebSockets enabled by default there's no toggle needed.

Just make sure you're NOT on a Free plan with more than 5 connections (limit is 5; extra gets HTTP 429).

Make sure your Startup Command in Configuration => General settings matches:

gunicorn -w 1 -k uvicorn.workers.UvicornWorker main:app -b 0.0.0.0:$PORT --timeout 240

-b 0.0.0.0:$PORT ensures Gunicorn listens on the correct port.

$PORT aligns with what the Azure reverse proxy expects.

Test the example locally and then deploy:

Clone the sample from Azure’s GitHub:
git clone https://github.com/Azure/app-service-linux-docs.git cd app-service-linux-docs/HowTo/WebSockets/use_websockets_with_fastapi pip install -r requirements.txt uvicorn main:app --reload --host 0.0.0.0 --port 8000

Confirm ws://localhost:8000/ws works locally.

Deploy to Azure (via zip, GitHub or Azure CLI), set the startup command as above.

Test on Azure: ws://<yourapp>.azurewebsites.net/ws using a simple WebSocket client.

Capture logs and handshake details:

Use az webapp log tail to get real-time output, it will show if handshake is received or dropped

Use browser Developer Tools => Network tab => WS frames to inspect status and confirm “Upgrade” request is sent.

https://www.uvicorn.org/deployment/#gunicorn
https://learn.microsoft.com/en-us/answers/questions/1689721/troubleshooting-websocket-connection-issues-in-azu

Let me know if you have any further assistances needed.

Answer accepted by question author

Bhargavi Naragani 7,940 Moderator

Hi Prasanna Sai Kommineni,

I'm glad that you were able to resolve your issue and thank you for posting your solution so that others experiencing the same thing can easily reference this!

Since the Microsoft Q&A community has a policy that "The question author cannot accept their own answer. They can only accept answers by others ", I'll repost your solution in case you'd like to "Accept " the answer.

Issue:

WebSocket Connection Fails on Azure Python Web App (No Response Headers)

Solution:

When we checked the config in az login console it shows websocketsEnabled as false, we ran the command to update the config Then websocket handshake was successful.

Please click Accept Answer and kindly upvote it so that other people who faces similar issue may get benefitted from it.

0 comments

1 additional answer

Your answer

Answer 1

Prasanna Sai Kommineni 40

When we checked the config in az login console it shows websocketsEnabled as false ,We ran the command to update the config Then websocket handshake was successful .

0 comments

Share via

WebSocket Connection Fails on Azure Python Web App (No Response Headers)

1 additional answer

Your answer