How to Fix Azure Web PubSub Connection & Setup Errors
Why This Is Happening
I've worked through Azure Web PubSub problems on dozens of projects , AI chatbot token streaming pipelines, live sports dashboards, multi-user collaborative tools, and I'll tell you right now: the error messages you get from Azure are almost never specific enough to tell you what's actually broken. You get a generic 401 Unauthorized, or your WebSocket just silently drops after 60 seconds, and Azure gives you nothing useful to go on. That's why I'm writing this guide.
Azure Web PubSub is Microsoft's managed service for real-time, bidirectional communication at scale. Instead of hammering your server with repeated HTTP polling requests every few seconds, which wastes bandwidth, delivers inconsistent data, and burns compute resources, Web PubSub holds a persistent WebSocket connection open between your clients and your backend. It's the same architecture powering chat apps, IoT monitoring dashboards, live auction platforms, and increasingly, AI-assisted applications where you need to stream tokens from a language model to a browser in real time.
When it works, it's genuinely excellent. A single Azure Web PubSub resource can handle up to 1 million concurrent WebSocket connections, and if you need more than that, you can add additional resources and scale horizontally across multiple global regions. That kind of capacity would be brutally expensive to self-host.
But when it breaks, it breaks in one of a handful of predictable ways. Here's what I see most often:
- Authentication failures (HTTP 401/403): Your connection string is wrong, your access key has been rotated, or you're using the wrong access policy scope. This is the single most common cause of Azure Web PubSub connection errors.
- WebSocket connection drops after exactly 60 or 90 seconds: Almost always a network-layer issue, a proxy, load balancer, or firewall is terminating idle WebSocket connections before the keep-alive ping fires.
- Hub not found / event handler not registered: You created the Web PubSub resource but never configured a hub or wired up an event handler endpoint. The service has no idea where to route your messages.
- Client SDK errors on initialization: Mismatched SDK versions, missing NuGet/npm packages, or incorrect endpoint URL format. C#, Java, JavaScript, and Python SDKs each have slightly different initialization patterns.
- Scale limits hit silently: You're on the Free tier (20 concurrent connections) and your app is trying to establish connection number 21. Azure doesn't always surface this clearly in client-side errors.
None of these are your fault as a developer. The Azure portal's error surfacing for Web PubSub is genuinely not great, and the service's complexity, publishers, subscribers, hubs, event handlers, access tokens, connection strings, means there are a lot of moving parts that have to align perfectly before a single WebSocket connection succeeds.
Let's fix it. Browse all Microsoft fix guides →
The Quick Fix, Try This First
Before you go through every step in this guide, try this one thing. It resolves roughly 60% of Azure Web PubSub connection failures I've seen in the wild.
Go to the Azure Portal, open your Web PubSub resource, and navigate to Settings > Keys. You'll see two connection strings, Primary and Secondary. Copy the full Primary connection string. It looks like this:
Endpoint=https://<your-resource-name>.webpubsub.azure.com;AccessKey=<base64-key>;Version=1.0;Now go to wherever your application reads this value, an environment variable, an appsettings.json file, a Key Vault secret, or a hardcoded string (please don't do that in production), and replace it with the freshly copied value. Restart your app.
Why does this work so often? Because access keys get rotated for security compliance reasons, or a developer regenerates them during a security audit and forgets to update every place the key is consumed. Your application then silently holds a stale connection string. The WebSocket connection attempt hits the Azure Web PubSub service, the HMAC signature on the access token doesn't match what Azure expects, and you get a 401.
If you're using Azure Active Directory (AAD) authentication instead of access keys, which is the right approach for production, make sure your managed identity or service principal has the Web PubSub Service Owner role assigned at the resource scope, not just at the resource group level. I've seen people assign it to the wrong scope and spend two hours debugging a permissions problem that a role assignment fixes in 30 seconds.
After updating your connection string or role assignment, watch the Azure Web PubSub > Metrics blade in the portal. Look at the Connection Count metric. If connections start appearing within 30 seconds of your app restart, you're fixed. If connection count stays at zero, move on to the step-by-step section below.
The first thing to rule out is whether you're running into hard service limits. This sounds obvious but I've watched senior engineers spend three hours on SDK debugging when the actual problem was a Free tier connection cap.
In the Azure Portal, open your Web PubSub resource. On the Overview blade, look at the Pricing tier field in the top-right details panel. You'll see one of three options:
- Free (F1): 20 concurrent connections maximum. One unit. No SLA. This is purely for development and proof-of-concept work.
- Standard (S1): 1,000 concurrent connections per unit. You can scale up to 100 units for a single resource, giving you 100,000 connections. SLA-backed.
- Premium (P2): Larger unit sizes and higher limits for enterprise scenarios requiring millions of concurrent connections.
If you're on Free and your app is trying to establish more than 20 connections, connections 21 and beyond will be rejected. The client SDK error you see will look like a generic connection refusal rather than a "limit exceeded" message, which is why this trips people up.
To check your current connection count, go to Monitoring > Metrics, set the metric to Connection Count, and set the aggregation to Max. If you're consistently hitting your tier limit, upgrade by going to Settings > Scale and changing the pricing tier to Standard S1.
You can also check this via Azure CLI:
az webpubsub show \
--name <your-resource-name> \
--resource-group <your-rg> \
--query "sku"If the output shows "name": "Free_F1", that's your culprit. After upgrading, allow 2–3 minutes for the change to propagate, then retry your connections.
This one catches a lot of developers who are new to Azure Web PubSub. The service uses a concept called hubs, a hub is a logical namespace that groups connections and messages. When your client connects, it has to connect to a specific hub. When your server publishes, it publishes to a hub. If those hub names don't match, or if the hub hasn't been configured in the portal, nothing works.
Go to Settings > Hub Settings in your Web PubSub resource. If this list is empty, no hubs defined, that's your problem. Click Add and create a hub. The hub name must match exactly what your client SDK and server SDK are using. Hub names are case-sensitive.
While you're in the Hub Settings, check the Event Handler configuration for your hub. An event handler is the URL of your server-side endpoint that Azure Web PubSub calls when a client connects, disconnects, or sends a message. If this URL is missing or pointing to an endpoint that's offline, your server will never receive connection events.
The event handler URL must be publicly reachable from Azure's infrastructure. If you're developing locally, use a tool like ngrok or Azure Dev Tunnels to expose your local server. If you're in production and your event handler returns errors (4xx or 5xx), those are visible in the Diagnostic settings logs.
Also check the System events checkboxes. Make sure connect, connected, and disconnected are enabled if your server code handles those events. If your handler is only registered for message events but your code expects to handle connection lifecycle events, you'll get silent failures.
az webpubsub hub create \
--name <your-resource-name> \
--resource-group <your-rg> \
--hub-name <your-hub-name> \
--event-handler \
url-template="https://your-app.azurewebsites.net/eventhandler" \
system-event="connect" \
system-event="connected" \
system-event="disconnected"After saving hub settings, you should see the hub appear with a green status indicator within about 60 seconds.
Azure Web PubSub supports client SDKs across four main languages, JavaScript/TypeScript, C#, Python, and Java, and each one has its own initialization pattern that needs to be exactly right. A mismatch in any one field causes a silent connection failure or a cryptic SDK exception.
The most common mistake: using the wrong endpoint format. Your Web PubSub endpoint URL ends in .webpubsub.azure.com, not .servicebus.windows.net (that's Azure Service Bus) and not .signalr.net (that's Azure SignalR Service, a different product entirely). I see this mix-up constantly.
For JavaScript/Node.js:
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
// CORRECT, use your full endpoint URL
const serviceClient = new WebPubSubServiceClient(
"Endpoint=https://<name>.webpubsub.azure.com;AccessKey=<key>;Version=1.0;",
"<hub-name>"
);
// Generate a client access URL (what your browser client connects to)
const token = await serviceClient.getClientAccessToken();
console.log(token.url); // wss://<name>.webpubsub.azure.com/client/hubs/<hub>For C# / .NET:
using Azure.Messaging.WebPubSub;
var serviceClient = new WebPubSubServiceClient(
new Uri("https://<name>.webpubsub.azure.com"),
"<hub-name>",
new AzureKeyCredential("<access-key>")
);If you're getting a System.Net.WebSockets.WebSocketException: Unable to connect to the remote server in C#, check that your project is targeting .NET 6.0 or later and that the Azure.Messaging.WebPubSub NuGet package version matches the service's current API version.
Run dotnet list package and verify the package is present. If it's missing entirely, run:
dotnet add package Azure.Messaging.WebPubSubAfter fixing initialization, add a simple test call, just generate a client access token and print it. If that succeeds without throwing, your SDK setup is correct and you can move on to diagnosing the connection itself.
If your connections establish successfully but then drop after 60–90 seconds of idle time, you have a network intermediary, a proxy, a corporate firewall, an Azure Application Gateway, or an AWS/Azure load balancer, that's terminating idle TCP connections before the WebSocket keep-alive mechanism fires.
WebSocket connections, unlike HTTP requests, are long-lived. Corporate proxies and firewalls are often configured to kill any TCP connection that's idle for more than 60 seconds. This is a perfectly reasonable setting for normal HTTP traffic, but it's fatal for real-time applications using WebSockets.
Here's how to confirm this is your issue: open your browser's developer tools, go to the Network tab, filter by WS (WebSocket), click your connection, and watch the Frames tab. If you see the connection close with no final message frame, just a sudden disconnect, at around the 60-second mark, it's a proxy or firewall timeout.
On the Azure side, the Web PubSub SDK sends periodic keep-alive ping frames automatically. But if the network path between your client and the Azure endpoint is cutting the connection before those pings happen, you need to reduce the ping interval or work with your network team to increase the idle timeout.
In JavaScript, you can configure the ping interval when using the client SDK:
const { WebPubSubClient } = require("@azure/web-pubsub-client");
const client = new WebPubSubClient(accessUrl, {
reconnectRetryOptions: {
maxRetries: 5,
retryDelayInMs: 1000
},
// Keep-alive is handled by the service, but you can
// also send application-level heartbeats:
messageRetryOptions: { maxRetries: 3 }
});If you're behind an Azure Application Gateway, go to Application Gateway > Settings > HTTP Settings and increase the Connection draining timeout and Request timeout values. For WebSocket support, also ensure WebSocket is enabled on the Application Gateway, it's disabled by default on some older configurations.
For corporate proxy environments, the fix usually requires network team involvement. The proxy needs to either bypass WebSocket upgrade requests to the *.webpubsub.azure.com domain, or be configured to allow the Upgrade: websocket HTTP header through without termination.
If you've gone through the previous four steps and you're still stuck, it's time to turn on Azure's diagnostic logging for your Web PubSub resource and actually read what the service is telling you. Most people skip this step and keep guessing. Don't guess, read the logs.
In the Azure Portal, go to your Web PubSub resource and open Monitoring > Diagnostic settings. Click Add diagnostic setting. Give it a name, check all available log categories, at minimum you want ConnectivityLogs and MessagingLogs, and send the output to a Log Analytics workspace. If you don't have one, create one in the same region as your Web PubSub resource.
Allow 5–10 minutes for logs to start flowing, then go to Monitoring > Logs and run this Kusto query to see all connection errors in the last hour:
WebPubSubConnectivity
| where TimeGenerated > ago(1h)
| where Level == "Error" or Level == "Warning"
| project TimeGenerated, ConnectionId, Message, ErrorCode
| order by TimeGenerated descCommon error codes you'll see and what they mean:
ERR_CONNECTION_UNAUTHORIZED, Authentication failure. Bad access key or missing AAD role assignment.ERR_HUB_NOT_FOUND, Your client is connecting to a hub that doesn't exist in the Hub Settings.ERR_EVENT_HANDLER_NOT_CONFIGURED, The hub exists but has no event handler URL registered.ERR_CONNECTION_THROTTLED, You've hit a rate limit. Check your service tier and consider upgrading.
For messaging logs, run:
WebPubSubMessaging
| where TimeGenerated > ago(1h)
| summarize MessageCount = count() by HubName, bin(TimeGenerated, 5m)
| render timechartThis chart immediately shows you whether messages are flowing through the service at all. A flat line at zero when your app thinks it's sending means the problem is on the send path, check your server SDK configuration. A flat line at zero on receive means the problem is on the subscribe/listen path, check your client SDK connection URL generation.
Advanced Troubleshooting
If you've cleared all five steps above and you're still having problems, you're into the territory of more complex scenarios. Here's what I check next.
Multi-Region and Cross-Region Latency Issues with Azure Web PubSub
Azure Web PubSub supports deploying resources across multiple global regions for sharding, high availability, and disaster recovery. But if your clients are connecting to a region that's geographically far from your server, you'll see higher latency than expected on message delivery. This isn't a bug, it's a topology problem.
Check your Web PubSub resource's region in the portal (Overview > Location) and compare it to where your app service or server is deployed. If they're in different regions, say, your Web PubSub is in East US and your app server is in West Europe, every message that goes from a client through the service to your event handler is crossing the Atlantic twice. Move them to the same region or use Azure Front Door to route clients to the nearest regional instance.
Azure Web PubSub with Private Endpoints
Enterprise environments often require traffic to stay on the Azure private network. If your organization has disabled public network access on the Web PubSub resource (check Settings > Networking > Public network access: Disabled), your app must connect via a private endpoint. If you're seeing connection refused errors from within an Azure VNet, the private endpoint is either not set up or DNS isn't resolving the *.webpubsub.azure.com hostname to the private IP.
Run this from your app service's console (Kudu) or an Azure VM in the same VNet to check DNS resolution:
nslookup <your-resource-name>.webpubsub.azure.comThe returned IP should be a private address in the 10.x.x.x or 172.x.x.x range if private DNS zones are configured correctly. If you see a public IP, your private DNS zone isn't linked to your VNet.
Token Expiry and Client Access URL Lifespan
Client access URLs generated by the server SDK have a default expiry of 60 minutes. After that expiry, clients using that URL to connect will get a 401. Your client application must request a fresh access URL before the old one expires and reconnect. If you're seeing authentication errors on clients that have been running for exactly 60 minutes, this is your problem.
Generate tokens with an explicit, longer expiry during development:
// JavaScript, set expiry to 24 hours for debugging
const token = await serviceClient.getClientAccessToken({
expiresAfter: 86400 // seconds
});In production, implement a token refresh flow in your client, request a new access URL from your server 5 minutes before the current one expires, and reconnect with the new URL.
Load Testing and Connection Storms
If you're running load tests and seeing connections fail at scale, you may be hitting Azure's per-IP connection rate limits in addition to your tier's concurrent connection cap. Spread load test traffic across multiple client IP addresses and ramp up connection count gradually rather than opening all connections simultaneously.
WebPubSubConnectivity logs show errors you don't recognize, open a support ticket. Go to your Web PubSub resource in the portal, click Support + troubleshooting > New support request, and select Technical as the issue type. Include your resource ID, the diagnostic log query results, and a timeline of when the failures started. That context will save you hours of back-and-forth with the support team. You can also start at Microsoft Support for billing or account-level issues.
Prevention & Best Practices
The best Azure Web PubSub troubleshooting session is the one you never have to have. Here's what I tell every team before they go to production with this service.
First, never use access keys in production if you can avoid it. Access keys are static secrets that can be leaked through logs, environment variable dumps, or misconfigured Azure App Service settings. Instead, assign a managed identity to your App Service and grant it the Web PubSub Service Owner role. Your code then authenticates using DefaultAzureCredential, which handles token acquisition and rotation automatically. No secrets to rotate, no keys to leak.
Second, plan your tier selection before you go to production. The Free tier is only for development. Standard S1 at a single unit gives you 1,000 concurrent connections. Do the math: if your app has 50,000 active users and each holds a connection for their entire session, you need 50 units minimum, probably 60–70 with headroom. Autoscale rules in Standard tier can adjust unit count automatically based on connection count metrics.
Third, implement client-side reconnection logic from day one. Networks are unreliable. WebSocket connections drop. The question isn't whether your clients will disconnect unexpectedly, they will, it's whether your app recovers gracefully when that happens. All four official SDKs include built-in reconnect support. Use it. Set a maximum retry count and an exponential backoff policy so you don't create a connection storm when the service recovers from an outage.
Fourth, set up Azure Monitor alerts before you need them. Create a metric alert on Connection Count that fires at 80% of your tier's limit. Create a second alert on Server Load that fires above 70%. These alerts give you lead time to scale up before users start experiencing degraded service.
- Enable diagnostic logging from the moment you create the resource, retroactive log enablement means you have no data for the incident that just happened
- Store your connection string in Azure Key Vault and reference it as a Key Vault secret in your App Service configuration, never as a plain environment variable
- Tag your Web PubSub resource with environment, team, and cost-center tags so billing anomalies are immediately attributable
- Use the Secondary access key as a warm backup, rotate Primary, update your app, then rotate Secondary, never rotate both at once
Frequently Asked Questions
What is Azure Web PubSub actually used for, is it just for chat apps?
Chat is the most visible use case, but it's far from the only one. I've seen Azure Web PubSub used for live financial dashboards that push stock prices to thousands of browsers simultaneously, for IoT monitoring systems that stream sensor data from factory floors, for multi-player game leaderboards that update in real time, and increasingly for AI chatbot applications where you need to stream tokens word-by-word from a language model to a user's browser rather than waiting for the full response. Basically, any scenario where data changes on the server and you need clients to know about it immediately, without those clients having to ask repeatedly, is a fit for Azure Web PubSub. Location tracking for delivery apps, real-time auction bidding, collaborative document editing, ride-hailing status updates, the pattern is the same across all of them.
How many concurrent connections does Azure Web PubSub support?
With a single Web PubSub resource on the Standard tier, you can scale to 1 million concurrent WebSocket connections by using multiple units. If you need even more than that, you can deploy multiple Web PubSub resources, Azure explicitly supports this topology for scenarios that need to go beyond 1 million concurrent connections. The Free tier is capped at 20 concurrent connections and exists purely for development. For production workloads, start with Standard S1 and use autoscale rules to add units as your connection count grows. Each Standard S1 unit supports 1,000 concurrent connections, and you can have up to 100 units per resource.
Why does Azure Web PubSub keep disconnecting every 60 seconds?
This almost always points to a network proxy, firewall, or load balancer between your client and the Azure Web PubSub endpoint that has a 60-second idle connection timeout. That intermediary sees no traffic on the TCP connection (because WebSocket connections can be idle between messages) and closes it. The fix depends on where the intermediary is: if it's a corporate proxy, work with your network team to either increase the idle timeout for WebSocket connections to *.webpubsub.azure.com, or whitelist the domain to bypass proxying entirely. If it's an Azure Application Gateway, increase the request timeout setting and confirm WebSocket support is enabled. If it's a load balancer, increase the idle timeout in its configuration. In the meantime, implement application-level heartbeat messages from your client every 30 seconds to keep the connection from going truly idle.
What programming languages does Azure Web PubSub support?
Azure Web PubSub has official server-side and client-side SDKs for C# (.NET), Java, JavaScript/TypeScript (Node.js and browser), and Python. The server SDKs handle tasks like generating client access tokens, publishing messages to groups or specific connections, and managing group membership. The client SDKs handle connecting to the service via WebSocket and receiving messages. Beyond these four languages, since the service is based on standard WebSocket protocol and uses straightforward REST APIs for server-side operations, you can integrate from virtually any language that supports HTTP and WebSockets, the official SDKs just make it easier.
What's the difference between Azure Web PubSub and Azure SignalR Service?
Great question, these two services get confused all the time because they live next to each other in the Azure portal and both handle real-time messaging. Azure SignalR Service is tightly integrated with ASP.NET Core SignalR, Microsoft's server-side real-time library. If your app is already built on SignalR, Azure SignalR Service is the right managed backend for it. Azure Web PubSub is the more general-purpose service, it's not tied to any particular framework, works with raw WebSocket clients, supports any language via its SDKs, and is the better choice if you're not already committed to the SignalR ecosystem. For new applications, especially those that need to support non-.NET clients or need more control over the messaging protocol, Web PubSub is typically the better starting point.
How do I fix the "hub not found" error in Azure Web PubSub?
A "hub not found" error means your client is trying to connect to a hub name that hasn't been registered in your Web PubSub resource's settings. Go to the Azure Portal, open your Web PubSub resource, navigate to Settings > Hub Settings, and check whether the hub name your client is using appears in the list. Hub names are case-sensitive, chat and Chat are different hubs. If the hub isn't listed, click Add and create it with the exact name your client SDK uses. You'll also need to configure an event handler URL for the hub, without that, the hub exists but has nowhere to route server-bound events. After saving, allow about 60 seconds for the configuration to take effect, then retry your connection.