Troubleshooting Connectivity Issues in Azure Synapse Analytics¶

Home > Troubleshooting > Connectivity Troubleshooting

This guide covers common connectivity and network-related issues in Azure Synapse Analytics, providing diagnostic approaches and solutions for establishing reliable connections to your Synapse workspace and its components.

Common Connectivity Issue Categories¶

Connectivity issues in Azure Synapse Analytics typically fall into these categories:

1. Networking Configuration: Firewall rules, private endpoints, network security groups
2. Authentication Problems: Token errors, identity issues, credential failures
3. Service Availability: Regional outages, service health incidents
4. Client Configuration: Driver issues, client tool misconfiguration
5. Cross-Service Integration: Problems connecting Synapse to other Azure services

Networking Configuration Issues¶

Firewall Rules and IP Restrictions¶

Symptoms:

• Connection timeout errors
• "Cannot connect to server" messages
• Inconsistent connectivity (works from some locations but not others)

Solutions:

1. Verify IP allowlisting:
2. Check if client IP is allowed in Synapse firewall settings
3. Ensure IP ranges cover all required client locations

# PowerShell: View firewall rules
Get-AzSynapseFirewallRule -WorkspaceName "synapseworkspace" -ResourceGroupName "resourcegroup"

# PowerShell: Add IP address to firewall
$ip = (Invoke-WebRequest -uri "https://api.ipify.org/").Content
New-AzSynapseFirewallRule -WorkspaceName "synapseworkspace" -ResourceGroupName "resourcegroup" -Name "AllowMyIP" -StartIpAddress $ip -EndIpAddress $ip

1. Configure "Allow Azure services":
2. Enable "Allow Azure services and resources to access this workspace" option

3. Useful for connections from other Azure resources

4. Check for dynamic IP issues:

5. If using VPN or dynamic IP allocation, connections might fail after IP changes
6. Consider using a gateway or fixed IP solution

Private Endpoint Configuration¶

Symptoms:

• Can't connect to Synapse when using private endpoints
• DNS resolution failures
• Connections working from VNet but not elsewhere

Solutions:

1. Verify private endpoint provisioning:
2. Check that private endpoints show "Succeeded" status

3. Validate connection group status

4. Check DNS configuration:

5. Ensure private DNS zones are correctly linked to VNets
6. Verify DNS records are properly created

# PowerShell: Check DNS records in private zone
Get-AzPrivateDnsRecordSet -ResourceGroupName "resourcegroup" -ZoneName "privatelink.sql.azuresynapse.net"

1. Test DNS resolution:
2. Use nslookup to verify DNS resolution from client machine
3. Check if the workspace name resolves to private IP

# From a VM in the connected VNet
nslookup yourworkspace.sql.azuresynapse.net

1. Review network security groups (NSGs):
2. Verify NSGs allow required traffic
3. Check for deny rules that might block connectivity

Network Security Groups (NSGs)¶

Symptoms:

• Intermittent connectivity issues
• Some services working while others fail
• Timeout errors rather than immediate rejections

Solutions:

1. Review NSG rules:
2. Check inbound and outbound security rules
3. Ensure required ports are open

1. Configure service tags:
2. Use Azure service tags like "Sql" in NSG rules

3. Implement least-privilege access model

4. Enable NSG flow logs:

5. Set up NSG flow logs to diagnose blocked connections
6. Review logs in Log Analytics or Traffic Analytics

# PowerShell: Enable NSG flow logs
$nsg = Get-AzNetworkSecurityGroup -Name "myNSG" -ResourceGroupName "resourcegroup"

$storageAccount = Get-AzStorageAccount -ResourceGroupName "resourcegroup" -Name "mystorageaccount"

Set-AzNetworkWatcherFlowLog -NetworkWatcherName "NetworkWatcher_region" -ResourceGroupName "NetworkWatcherRG" -TargetResourceId $nsg.Id -StorageAccountId $storageAccount.Id -EnableFlowLog $true -FormatType Json -FormatVersion 2

Authentication Problems¶

Token and Identity Issues¶

Symptoms:

• "Failed to authenticate" errors
• Token expiration messages
• Permission-related failures
• Single sign-on failures

Solutions:

1. Check Azure AD configuration:
2. Verify user exists in Azure AD tenant
3. Check for conditional access policies

4. Validate multi-factor authentication settings

5. Inspect token validity and claims:

6. Use jwt.ms to decode tokens
7. Check expiration times and claims

8. Verify correct audience and issuer

9. Review Azure AD app registration:

10. For application connections, check app registration settings
11. Ensure redirect URIs are properly configured

12. Verify required API permissions

13. Test with alternative credentials:

14. Try SQL authentication if available
15. Test with a different user account
16. Use admin account to isolate permission issues

Managed Identity Configuration¶

Symptoms:

• "Failed to obtain access token" errors
• Services unable to access each other
• Permission denied errors when using managed identities

Solutions:

1. Verify managed identity is enabled:
2. Check that managed identity is enabled for services

3. Validate system-assigned vs. user-assigned configuration

4. Check RBAC assignments:

5. Ensure managed identity has appropriate RBAC roles
6. Common roles include "Storage Blob Data Contributor" for ADLS access

# PowerShell: View role assignments for managed identity
$id = (Get-AzSynapseWorkspace -Name "synapseworkspace" -ResourceGroupName "resourcegroup").Identity.PrincipalId

Get-AzRoleAssignment -ObjectId $id

# PowerShell: Assign Storage Blob Data Contributor role
$storage = Get-AzStorageAccount -ResourceGroupName "resourcegroup" -Name "storage"

New-AzRoleAssignment -ObjectId $id -RoleDefinitionName "Storage Blob Data Contributor" -Scope $storage.Id

1. Refresh tokens:
2. Use PowerShell or Azure Cloud Shell to test token acquisition
3. Validate that identity can access required resources

Service Availability¶

Regional Outages and Service Health¶

Symptoms:

• Widespread connectivity issues
• All components of Synapse affected
• Similar issues reported by others

Solutions:

1. Check Azure Service Health:
2. Review Azure Status
3. Check for active advisories or incidents

4. Look for Synapse-specific or regional issues

5. Review service health in Azure portal:

6. Go to Azure portal > Service Health
7. Filter for Synapse Analytics service

8. Check for current or planned maintenance

9. Configure service health alerts:

10. Set up alerts for service issues
11. Receive notifications for planned maintenance

# PowerShell: Create service health alert
$condition = New-AzActivityLogAlertCondition -Field "category" -Equal "ServiceHealth" `
               -AndCondition (New-AzActivityLogAlertCondition -Field "properties.serviceHealthData.service" -Equal "Synapse Analytics")

New-AzActivityLogAlert -Location "Global" -Name "SynapseHealthAlert" `
                         -ResourceGroupName "resourcegroup" `
                         -Condition $condition `
                         -ActionGroupId "/subscriptions/subid/resourceGroups/resourcegroup/providers/microsoft.insights/actionGroups/actiongroup"

Client Configuration¶

Driver and Client Tool Issues¶

Symptoms:

• Connection errors from specific tools or applications
• Authentication works in some tools but not others
• "Driver not found" or version incompatibility errors

Solutions:

1. Update ODBC/JDBC drivers:
2. Use the latest SQL Server drivers
3. Check for compatibility with Azure Synapse

# Example connection string for JDBC
jdbc:sqlserver://<workspace-name>.sql.azuresynapse.net:1433;database=<database>;user=<user>@<workspace-name>;password=<password>;encrypt=true;trustServerCertificate=false;hostNameInCertificate=*.sql.azuresynapse.net;loginTimeout=30;

1. Check TLS/encryption settings:
2. Ensure TLS 1.2+ is enabled
3. Verify encryption is enabled in connection strings

4. Check for certificate validation issues

5. Validate connection strings:

6. Use correct server naming format: <workspace-name>.sql.azuresynapse.net
7. Include all required parameters

8. Test connection string with a simple tool like SSMS

9. Test with different tools:

10. Try SQL Server Management Studio
11. Test with Azure Data Studio
12. Use sqlcmd command-line utility

# Using sqlcmd
sqlcmd -S <workspace-name>.sql.azuresynapse.net -d master -U <username> -P <password> -I -Q "SELECT @@VERSION"

Cross-Service Integration¶

Storage Connectivity Issues¶

Symptoms:

• Synapse can't access storage accounts
• "Access denied" when reading/writing data
• Permission errors during query execution

Solutions:

1. Check storage account network settings:
2. Verify firewall rules allow Synapse access
3. Check if "Allow trusted Microsoft services" is enabled

4. Ensure private endpoint configuration if used

5. Verify user permissions:

6. Verify Synapse managed identity has proper RBAC roles
7. Check for Storage Blob Data Reader/Contributor roles

8. Verify ACLs if using hierarchical namespace

9. Test storage connectivity:

-- SQL Serverless Pool test
SELECT TOP 10 *
FROM OPENROWSET(
    BULK 'https://storageaccount.dfs.core.windows.net/container/folder/*',
    FORMAT = 'CSV',
    PARSER_VERSION = '2.0',
    HEADER_ROW = TRUE
) AS [result]

# PySpark test
df = spark.read.csv("abfss://container@storageaccount.dfs.core.windows.net/folder/")
df.show(5)

Key Vault Integration Issues¶

Symptoms:

• Can't retrieve secrets from Key Vault
• "Access denied" errors when using linked services
• Authentication failures for services using Key Vault credentials

Solutions:

1. Check Key Vault access policies:
2. Ensure Synapse managed identity has "Get" and "List" permissions
3. Verify no deny assignments blocking access

# PowerShell: Grant Key Vault permissions
$id = (Get-AzSynapseWorkspace -Name "synapseworkspace" -ResourceGroupName "resourcegroup").Identity.PrincipalId

Set-AzKeyVaultAccessPolicy -VaultName "keyvault" -ObjectId $id -PermissionsToSecrets Get,List

1. Verify network access:
2. Check Key Vault firewall settings

3. Ensure Synapse can reach Key Vault (public or private endpoint)

4. Test Key Vault linked service:

5. Create a simple linked service to Key Vault
6. Test connection from Synapse UI
7. Check for specific error messages

Diagnosing Connection Issues¶

Diagnostic Tools¶

1. Network Packet Capture:
2. Use tools like Wireshark or Network Watcher Packet Capture

3. Look for connection attempts, failures, or timeouts

4. Connection Test Tools:

5. Use Test-NetConnection (PowerShell) to check port connectivity
6. Run network trace to identify connectivity problems

# PowerShell: Test SQL connectivity
Test-NetConnection -ComputerName "<workspace-name>.sql.azuresynapse.net" -Port 1433

1. Azure Network Watcher:
2. Use Connection Troubleshoot feature
3. Check for network topology issues
4. Validate NSG and routing configuration

# PowerShell: Test connection with Network Watcher
$source = Get-AzNetworkInterface -Name "sourceNIC" -ResourceGroupName "sourceRG"
$dest = Get-AzNetworkInterface -Name "destNIC" -ResourceGroupName "destRG"

Test-AzNetworkWatcherConnectivity -NetworkWatcherName "NetworkWatcher_region" `
                                    -ResourceGroupName "NetworkWatcherRG" `
                                    -SourceId $source.Id `
                                    -DestinationId $dest.Id `
                                    -DestinationPort 1433

Logging and Monitoring¶

1. Enable diagnostic logging:
2. Configure Azure Monitor for Synapse
3. Send logs to Log Analytics workspace
4. Set up alerting for connection failures

# PowerShell: Enable diagnostic settings
$workspace = Get-AzOperationalInsightsWorkspace -ResourceGroupName "resourcegroup" -Name "logworkspace"
$synapse = Get-AzSynapseWorkspace -Name "synapseworkspace" -ResourceGroupName "resourcegroup"
Set-AzDiagnosticSetting -Name "SynapseDiagnostics" -ResourceId $synapse.Id `
  -WorkspaceId $workspace.ResourceId -Enabled $true `
  -Category "SynapseRbacOperations", "GatewayApiRequests", "BuiltinSqlReqsEnded", "IntegrationPipelineRuns"

1. Query logs for connection failures:
2. Use KQL queries to search for error patterns

-- Log Analytics query for SQL connection failures
SynapseBuiltinSqlPoolRequestsEnded
| where StatusCode != 0
| where TimeGenerated > ago(24h)
| order by TimeGenerated desc

1. Monitor network health:
2. Set up connection monitors in Network Watcher
3. Create dashboards for network performance metrics

Best Practices for Reliable Connectivity¶

1. Implement proper network design:
2. Use private endpoints for enhanced security
3. Design appropriate network segmentation

4. Implement hybrid connectivity patterns correctly

5. Create comprehensive firewall rules:

6. Document all required IP ranges
7. Review and audit firewall rules regularly

8. Consider using service endpoints where appropriate

9. Plan for disaster recovery:

10. Document connection procedures
11. Create connectivity testing runbooks

12. Prepare for regional outages or service disruptions

13. Use managed identities:

14. Leverage managed identities for service-to-service authentication
15. Reduce reliance on connection strings with secrets
16. Implement least-privilege access model

Related Topics¶

• Network Security Configuration for Synapse
• Private Link Configuration Guide
• Authentication Best Practices
• Monitoring and Logging Setup

External Resources¶

• Azure Synapse Documentation: Connectivity Architecture
• Microsoft Learn: Network Security for Synapse
• Azure Private Link Documentation