Fix Azure Synapse Analytics Workspace Errors
Why This Is Happening
I've seen this exact situation play out on dozens of enterprise Azure tenants: someone provisions an Azure Synapse Analytics workspace, everything looks fine in the portal, and then the moment they try to open Synapse Studio or connect a linked service, it just falls apart. An error message appears , often something vague like "Error 400" or the dreaded connection timeout , and suddenly a data pipeline that was supposed to go live this week is completely blocked.
The frustrating part? Azure Synapse Analytics workspace connectivity errors rarely tell you what's actually wrong. "Error code 9054" sounds serious but gives you zero direction. "Error 400 while loading workspace" could mean a dozen different things. That's by design in a way, Synapse sits at the intersection of networking, identity, storage, and compute, and when something breaks, the failure message typically comes from whichever layer first rejected the request, not the layer that actually caused the problem.
Here's the core picture of what tends to go wrong. The most common root cause I see is a mismatch between how the workspace was deployed and what the network actually expects. If you deployed a Synapse workspace using a GIT-based ARM template but forgot to include the Managed Virtual Network configuration, linked services will throw error code 9054 every time. The workspace is there, it looks healthy, but it's missing a foundational network component it needs to reach out to external data sources.
The second most common culprit is identity and permissions. When Synapse creates a workspace, it automatically generates a default linked service to your ADLS Gen2 storage account using the workspace's Managed Service Identity (MSI). That linked service can't be edited, it's baked in. But if your workspace identity was never granted the Storage Blob Data Contributor role on that storage account, every data operation fails with a "Forbidden" status. The error message says "ADLS Gen2 operation failed" which sounds like a storage issue, but it's actually an RBAC issue in disguise.
Then there's the private network scenario. Many enterprise teams rightly want to lock Synapse down, disable public network access, route everything through private endpoints. That's the right call from a security standpoint. But if the DNS configuration inside the virtual network isn't set up to correctly resolve Synapse's private endpoints, nothing connects. Tools like SSMS and Power BI stop working. Synapse Studio itself fails to load. The workspace isn't broken, the DNS is broken, and Synapse is just the thing that exposed it.
I know this is frustrating, especially when it's blocking data engineers from doing actual work. The good news is that every single one of these failure modes has a known, documented fix. Let's walk through them. Browse all Microsoft fix guides →
The Quick Fix, Try This First
Before going deep into network settings and private endpoints, start with the two fastest checks that resolve the majority of Synapse Studio access issues.
First: check your browser. Synapse Studio is a web application, and it's sensitive to cached credentials, browser extensions, and pop-up blockers. I've personally seen cases where the only thing wrong was a stale authentication cookie. Clear your browser's cookies and cached data completely, then try again. If that doesn't work, open a private/incognito window. If Synapse Studio loads in private mode but not normally, the issue is browser state, not Azure config. Try a different browser entirely (Edge and Chrome tend to be most compatible).
Second: check your own access permissions. This one catches people off guard. You might have created the workspace but not have the right role assigned in Synapse itself.
Here's how to verify quickly:
- Open the Azure portal and navigate to your Synapse workspace resource.
- In the left menu, click Access control (IAM).
- Click View my access at the top.
- Confirm you have either Owner or Contributor at the workspace scope.
If you're missing those roles, that's your problem right there, get an Owner to assign you the correct role, then try again.
Also check your IP is whitelisted. While you're in the portal on the Synapse workspace page, click Networking in the left menu. Look at the firewall rules table. Your current public IP address needs to be in there. If it's not, click Add client IP and save the rule.
One more fast check: make sure your local firewall and corporate network aren't blocking the ports Synapse needs. Synapse Studio requires outbound TCP on ports 80, 443, and 1443. For DNS resolution to work, you also need outbound UDP on port 53. If you're connecting with SSMS or Power BI, add TCP port 1433 to that list. Corporate proxies and firewalls often silently block 1443, and that's exactly the port Synapse Studio uses for workspace-level calls.
Error code 9054 shows up when you can't connect to linked services, and it almost always traces back to one specific deployment mistake: the workspace was deployed from a GIT-sourced ARM template that didn't include the Managed Virtual Network configuration.
Here's the thing about Managed Virtual Networks in Synapse, you can only apply them at workspace creation time. There's no "enable Managed VNet" toggle you can flip after the fact. The network type is baked into the workspace at provisioning. So if you're hitting error 9054 on an existing workspace that was deployed without it, you're looking at either recreating the workspace with the correct template or working around the limitation through other means.
To fix this for future deployments, make sure your ARM or Bicep template includes the Managed Virtual Network configuration explicitly. In your workspace resource definition, the managedVirtualNetwork property must be set:
"managedVirtualNetwork": {
"type": "ManagedVirtualNetworkSettings",
"preventDataExfiltration": true,
"allowedAadTenantIdsForLinking": []
}For an existing workspace already in production without a Managed VNet, work with your Azure architect to scope the impact of a workspace recreation, or explore whether Managed Private Endpoints can be configured through an alternative network path.
After applying the correct template to a new workspace, open Synapse Studio and navigate to Manage > Linked Services. Try creating or testing a linked service connection. If the error 9054 is gone and the test connection succeeds, you're good.
The error message reads something like "ADLS Gen2 operation failed for: Storage account operation '' get failed with Operation returned an invalid status code 'Forbidden.'" I've had data engineers panic over this one because it sounds like the storage account itself is rejecting the workspace, but the real issue is simpler than that.
When Synapse creates your workspace, it automatically creates a default Linked Service that connects to your associated ADLS Gen2 storage account. This Linked Service uses the workspace's Managed Service Identity (MSI) as its authentication method. You can't change that, it's intentional. But that MSI needs to actually have permission to access the storage account, and Azure doesn't assign that permission automatically during workspace provisioning.
Here's how to fix it:
- In the Azure portal, navigate to your ADLS Gen2 storage account (not the Synapse workspace, the storage account itself).
- Click Access control (IAM) in the left menu.
- Click Add > Add role assignment.
- Select the role Storage Blob Data Contributor.
- On the Members tab, select Managed identity, then click Select members.
- Find your Synapse workspace's managed identity, it will have the same name as your workspace.
- Click Select, then Review + assign.
Role assignments in Azure can take up to a few minutes to propagate. Wait about 2-3 minutes, then go back to Synapse Studio and retry your data operation. The "Forbidden" error should be gone. If you're managing multiple workspaces or environments, this is one of those permission assignments that needs to be in your deployment checklist every single time.
Error 400 while loading your Synapse workspace in Studio is one of the more maddening errors because it's caused by misconfiguration, and "misconfiguration" covers a lot of ground. In practice, this breaks down into two main scenarios: connecting from a restricted network, or a broken Private Endpoint DNS setup.
Scenario A: Connecting from a restricted network. If your machine is on a corporate network with strict outbound filtering, Synapse Studio may fail to reach all the endpoints it needs. Go back to your firewall and proxy rules and verify the three TCP ports (80, 443, 1443) and UDP 53 are all open outbound. Also check whether your network has any URL-based filtering, Synapse Studio calls several Azure endpoints during initialization, and any one blocked URL can produce this error.
Scenario B: Private Endpoint DNS misconfiguration. If your workspace uses Private Endpoints, every Synapse hostname needs to resolve to the private IP inside your virtual network, not the public Azure IP. When DNS isn't configured correctly, requests either fail to resolve entirely or resolve to the wrong IP and get blocked.
To verify DNS is routing correctly, run this from a machine inside your virtual network:
Resolve-DnsName <your-workspace-name>.dev.azuresynapse.netThe IP address in the response should be a private IP within your VNet's address space (typically 10.x.x.x or 192.168.x.x). If it resolves to a public Azure IP, your Private DNS Zone is either missing or not linked to the VNet. You'll need to add an Azure Private DNS Zone for privatelink.azuresynapse.net and link it to the virtual network that contains your private endpoints.
This error hits when a workspace has data exfiltration protection (DEP) enabled and public network access is explicitly set to "Yes" for denial. The full error looks like: "An instance-specific error occurred while establishing a connection to SQL Server. Connection was denied since Deny public network access is set to Yes."
This is actually a security feature working as intended, but if it's blocking legitimate users or applications, you need to set up the right private connectivity path. There are two primary options depending on your scale.
For individual users or small teams: Set up a Point-to-Site VPN connection. This lets each user connect their machine directly into the Azure virtual network as if they were physically on it. Once connected through the VPN, their requests enter through the private network path and aren't subject to the public network block.
For larger enterprise teams: Use ExpressRoute. This is a dedicated private circuit between your on-premises network and Azure, no traffic traverses the public internet at all. ExpressRoute is the enterprise standard for this exact scenario and pairs well with DEP-enabled Synapse workspaces.
Regardless of which path you choose, you'll also need to make sure a Self-Hosted Integration Runtime (SHIR) is created while DEP is enabled. Don't install the SHIR after the fact, create it during or immediately after workspace setup. This is a common sequencing mistake that causes integration runtime connectivity failures later.
After your VPN or ExpressRoute is connected and DNS resolves to private IPs, retry the connection from SSMS or Power BI. TCP port 1433 must be open through your private path for SQL-based connections.
The full error reads: "Per-machine installation is stopped because there is existing per-user gateway installation." This one trips people up because it sounds like a software conflict, but it's actually an architectural constraint.
Synapse (unlike Azure Data Factory) does not support the Self-Hosted Integration Runtime sharing feature. That means one VM can only host one SHIR instance. If there's already a per-user gateway installed on the target VM, you cannot install a per-machine SHIR on top of it. The two installation types conflict at the VM level.
The fix is straightforward but requires infrastructure: provision a separate, dedicated Virtual Machine for each Integration Runtime instance you need. Don't try to consolidate multiple SHIRs onto a single host.
Here's the correct setup process for a clean SHIR installation:
- Spin up a new Windows Server VM in Azure (or on-premises if required).
- In Synapse Studio, go to Manage > Integration Runtimes > New.
- Select Self-Hosted and follow the wizard to generate the authentication key.
- On the new dedicated VM, download the latest Integration Runtime installer from Microsoft.
- During install, choose per-machine installation mode (not per-user).
- Paste the authentication key when prompted.
Once registered, the SHIR status will show as Running in Synapse Studio under Manage > Integration Runtimes. If you see it stuck in "Offline" after installation, check that the VM can reach the Microsoft service bus endpoints on TCP port 443.
Advanced Troubleshooting
When the standard fixes don't resolve your Azure Synapse Analytics workspace connectivity issue, it's time to go deeper. Here's how I approach the harder cases.
Error Code 2108, Endpoint Unreachable
Error code 2108 with the message "Request didn't reach the server from the client" is a network-layer failure. The client sent a request; it never arrived. This happens in workspaces configured with a Managed Virtual Network and Data Exfiltration Protection enabled, where traffic must flow through specific private paths.
Check these in order:
- Network connectivity: From a machine inside the VNet, try to reach the Synapse endpoint over TCP 443 using
Test-NetConnectionin PowerShell. - DNS resolution: Use
Resolve-DnsNameto confirm all Synapse endpoints resolve to private IPs. Key hostnames include<workspace>.dev.azuresynapse.net,<workspace>.sql.azuresynapse.net, and<workspace>-ondemand.sql.azuresynapse.net. - Certificate validation: If your network uses SSL inspection or a custom certificate authority, the intercepted certificates can cause server certificate validation failures that look identical to network failures from the client side.
- Timeout misconfiguration: Some proxy appliances time out long-running Synapse Studio WebSocket connections. Check your proxy timeout settings, Synapse Studio uses persistent connections that can run longer than default proxy idle timeouts.
Running the PowerShell Diagnostic Script
Microsoft's official connectivity diagnostic script is the fastest way to identify exactly which endpoint is unreachable. Download and run it from a machine on the same network as the affected users. The script tests each required Synapse endpoint and shows you pass/fail for each one. When you open a support ticket, attach this script's output, it dramatically speeds up the resolution time.
# Run from the affected machine, output shows which endpoints fail
Test-NetConnection -ComputerName <workspace>.dev.azuresynapse.net -Port 443
Test-NetConnection -ComputerName <workspace>.sql.azuresynapse.net -Port 1433
Test-NetConnection -ComputerName <workspace>-ondemand.sql.azuresynapse.net -Port 1433ADLS Gen1 via Service Principal, GIT Mode Limitation
If your linked service for ADLS Gen1 uses a Service Principal for authentication and lives in your GIT repo, you'll find you cannot publish it to Synapse live mode. This is a known platform limitation, not a bug, not a misconfiguration. Linked Services of this type in GIT cannot be published directly. The workaround is to recreate the linked service manually in live mode rather than through the GIT-integrated publish pipeline.
Table Lock Issues with SAP ECC Data
If you're pulling data from SAP ECC and seeing table lock issues during extraction, this is by design. Synapse uses transaction isolation to maintain data consistency during reads, which can cause locks to appear on the SAP side. This is not something to fix in Synapse, it's a normal behavior. Work with your SAP team to schedule extractions during lower-activity windows or use an SAP extraction method that doesn't trigger locks at the application level.
Escalate to Microsoft Support when you've confirmed DNS resolution is correct, firewall ports are open, RBAC is properly assigned, and you're still hitting connectivity failures. At that point, the issue is likely at the Azure platform level, a misconfigured private endpoint on Microsoft's side, a regional service issue, or a tenant-level configuration that requires Microsoft's tooling to inspect. Open a Severity B or A support ticket, attach your PowerShell diagnostic output, and ask specifically for an Azure Synapse Networking engineer. Generic support routing can add days to resolution time.
Prevention & Best Practices
The best Azure Synapse Analytics workspace troubleshooting is the kind you never have to do. These are the practices that prevent the most common failure modes before they happen.
Plan your network architecture before you provision. The single most expensive mistake I see is deploying a Synapse workspace, building pipelines on top of it, and then realizing later that the network setup is wrong. Because the Managed Virtual Network type can only be set at creation time, changing your mind later means recreating the workspace from scratch. Decide upfront whether you need a Managed VNet with Data Exfiltration Protection, sketch out your private endpoint topology, and get DNS configured in your hub-and-spoke network before you run that first ARM deployment.
Build RBAC assignment into your deployment pipeline. Every time a Synapse workspace is provisioned, the workspace MSI needs Storage Blob Data Contributor on the associated ADLS Gen2 account. Every time. Make this a post-deployment step in your CI/CD pipeline or infrastructure-as-code template so it never gets missed. The same goes for Synapse RBAC roles, assign them in the same pipeline, not manually after the fact.
Use Private Endpoints with the correct DNS zones from day one. If your security policy requires private connectivity (and for production workloads, it should), deploy the Azure Private DNS Zones for privatelink.azuresynapse.net, privatelink.sql.azuresynapse.net, and privatelink.azuredatalakestore.net as part of the same Terraform or Bicep module that creates the workspace. Link each zone to every VNet that needs to resolve Synapse endpoints. Doing this after the workspace is live in production creates a change window risk.
Create your SHIR before enabling DEP. If you're enabling Data Exfiltration Protection on your workspace, create the Self-Hosted Integration Runtime during initial setup, before you lock down the network. Adding a SHIR after DEP is enabled requires more careful orchestration around the network rules that govern outbound traffic from the SHIR host VM.
- Add the Storage Blob Data Contributor role for the workspace MSI to every ADLS Gen2 account it needs to access, do this in your ARM/Bicep template, not manually.
- Document and verify your firewall allowlist for ports 80, 443, 1443 (TCP) and 53 (UDP) before going live, especially on corporate networks with outbound filtering.
- Run the Microsoft Synapse connectivity PowerShell diagnostic from each network zone that will access the workspace during initial setup, not after users start reporting problems.
- Keep one SHIR per VM, never attempt to consolidate multiple integration runtime instances onto a single host in Synapse.
Frequently Asked Questions
What is a private endpoint in Azure Synapse Analytics?
A private endpoint is a network interface that connects your Azure Virtual Network to a Synapse resource using a private IP address. Instead of your Synapse traffic going over the public internet, even if it's encrypted, it travels entirely within Microsoft's backbone network from your VNet to the Synapse service. In practical terms, it means you can block all public access to your Synapse workspace and still have your VMs, data pipelines, and on-premises tools connect to it securely. Each private endpoint you create gets its own private IP in your VNet's address space, and DNS is configured to resolve the Synapse hostnames to those private IPs instead of the public Azure IPs.
What is Azure Private Link and how does it work with Synapse?
Azure Private Link is the platform-level service that makes private endpoints possible. It creates a private connection between your virtual network and an Azure service, in this case, Synapse Analytics, without exposing traffic to the public internet. Think of Private Link as the pipe, and the private endpoint as the socket at the end of the pipe that plugs into your VNet. When you set up Private Link for Synapse, all connections from your VNet to Synapse go through that private path. This is especially important for Synapse workspaces with Data Exfiltration Protection enabled, where outbound traffic is strictly controlled to prevent data from leaving your approved network perimeter. Private Link Service is the underlying Azure infrastructure that enables publishers (like Microsoft's Synapse team) to offer their service over a private connection to consumer VNets.
How do I connect to Azure Synapse workspace resources from a restricted network?
There are a few paths here depending on how restricted your network is. First, make sure the required ports are open, TCP 80, 443, and 1443 outbound for Synapse Studio, UDP 53 for DNS, and TCP 1433 if you're connecting with SSMS or Power BI. If your organization blocks public internet access entirely, you'll need either a Point-to-Site VPN (good for a small number of users connecting from their own machines) or ExpressRoute (better for large teams or entire on-premises networks). Both route your traffic through private paths that bypass the public network block. You'll also need Private Endpoints deployed for your Synapse workspace with the corresponding Azure Private DNS Zones configured and linked to your VNet, so that DNS resolves Synapse hostnames to private IPs rather than public ones.
Why does Synapse Studio show "Error 403 Forbidden" when I open my workspace?
Error 403 when opening Synapse Studio is almost always a permissions issue or an IP address not being whitelisted in the firewall rules. First, go to your Synapse workspace in the Azure portal, open Access control (IAM), and click "View my access", confirm you have Owner or Contributor assigned at the workspace scope. Second, under Networking in the workspace settings, confirm your current public IP is listed in the firewall rules (click "Add client IP" if it's not). If both of those check out and you're still getting 403, try the browser fixes: clear cookies and cached data, use an incognito/private window, or switch to a different browser entirely. This error can also appear intermittently during workspace initialization, if it resolves after a page refresh, that's usually transient and not a configuration issue.
Can I install two Self-Hosted Integration Runtimes on the same VM in Synapse?
No, Synapse Analytics only supports one Self-Hosted Integration Runtime per Virtual Machine. If you try to install a second one on a VM that already has a SHIR (or any other gateway), you'll hit the "Per-machine installation is stopped because there is existing per-user gateway installation" error. This is a Synapse-specific limitation, Azure Data Factory does support SHIR sharing, but that feature doesn't carry over to Synapse. The correct approach is to provision a separate, dedicated VM for each SHIR instance you need. It adds infrastructure cost but it's the only supported path. Size the SHIR VMs appropriately for the data volumes they'll be moving, integration runtime performance is CPU and memory bound for large transformations.
Why did my Azure Synapse linked service start failing after I enabled Data Exfiltration Protection?
Data Exfiltration Protection (DEP) fundamentally changes how outbound traffic is controlled from your Synapse workspace. Once DEP is enabled, all managed compute resources in the workspace can only communicate with approved targets through Managed Private Endpoints, they can't make arbitrary outbound connections to the internet or to Azure services that don't have a Managed Private Endpoint configured. So if your linked service was previously connecting over the public network (or using a public endpoint for the target service), that path is now blocked. You need to create Managed Private Endpoints from within Synapse Studio (under Manage > Managed Private Endpoints) to each target data source. Also, make sure your Self-Hosted Integration Runtime was created after DEP was enabled, SHIRs created before DEP was turned on may not respect the new exfiltration controls correctly.