Azure Database Migration Service: Fix Common Errors
Why This Is Happening
I've worked through Azure Database Migration Service setup problems with dozens of teams , and let me tell you, the error messages you get from the Azure portal rarely tell you what's actually wrong. You kick off what should be a straightforward SQL Server to Azure SQL migration, and suddenly you're staring at a vague failure notification with no clear next step. That's genuinely frustrating, especially when a production migration window is ticking.
Azure DMS is a fully managed service designed to move databases from SQL Server, PostgreSQL, MySQL, and MongoDB into Azure's data platforms , with the option to do it online (minimal downtime) or offline. It sounds simple. In practice, there are several layers where things go sideways: resource provider registration, role-based access control assignments, source/target connectivity, migration mode mismatches, and automation script misconfiguration. Any one of these can silently block your migration or cause it to fail mid-run.
The most common root cause I see for Azure Database Migration Service setup failures is a missing resource provider registration, specifically Microsoft.AzureArcData. Azure DMS uses the Azure Arc readiness assessment engine under the hood to generate pre-migration compatibility reports. If your subscription hasn't registered that provider, the tracking resource creation step quietly fails, and downstream migration tasks can break in confusing ways. The portal attempts to register it for you automatically, but in environments with strict Azure Policy controls or limited subscription-level permissions, that auto-registration gets blocked.
The second most common issue is RBAC. Azure DMS has specific role requirements depending on what you're migrating to, Contributor on the target resource, Reader on the containing resource group, and Storage Account contributor rights if you're uploading backups from an SMB share. Miss any one of those, and you'll get a permissions error that looks generic but has a very specific fix.
Then there are the less obvious gotchas: TDE-encrypted databases aren't supported for migration through Azure DMS (that's a documented limitation, you need a different path). Logins migration isn't supported in the current Azure portal version. And if you're on a network with private endpoints, the connectivity configuration has to be done before you start the migration, not after.
This guide walks through every layer, from the one-minute fix to the deep enterprise scenarios. You'll find the exact commands, portal navigation paths, and configuration checks that actually resolve these issues. Browse all Microsoft fix guides →
The Quick Fix, Try This First
If your Azure Database Migration Service migration won't start, fails on the tracking resource creation step, or throws a permissions error immediately after you hit the migration launch button, this is the fix that resolves the majority of cases in under five minutes.
You need to manually register the Microsoft.AzureArcData resource provider on your subscription. Here's exactly how to do it in the Azure portal:
- Sign in to the Azure portal at portal.azure.com.
- In the left sidebar, click Subscriptions. If you don't see it, search "Subscriptions" in the top search bar.
- Select the subscription you're running Azure DMS migrations on.
- In the subscription blade, scroll down the left menu to Settings and click Resource providers.
- In the search box, type
AzureArcData. - You'll see Microsoft.AzureArcData in the list. If its status shows NotRegistered, select it and click the Register button at the top.
- Wait about 60–90 seconds and refresh the page. The status should change to Registered.
If you'd rather do this with one PowerShell command (and you should, it's faster), open Azure Cloud Shell or a local PowerShell session connected to your Azure account and run:
Register-AzResourceProvider -ProviderNamespace Microsoft.AzureArcDataOr if you prefer Azure CLI:
az provider register --namespace Microsoft.AzureArcDataAfter registration completes, go back to your Azure DMS migration and retry. In most cases this is all you needed. If the migration still fails after this, continue to the step-by-step section below, the next most likely culprit is an RBAC role gap.
Register-AzResourceProvider -ProviderNamespace Microsoft.AzureArcData to your migration runbook, it's idempotent, meaning it does nothing if already registered, so there's zero risk in always running it first.
This is the step that trips up almost every team doing their first Azure DMS SQL Server to Azure SQL Database migration. Azure DMS doesn't run with your personal credentials, it acts as a service, and that service needs specific permissions assigned on the right resources. Getting this wrong means you'll see either a generic "Authorization failed" error or, worse, the migration will appear to start and then fail silently partway through.
Here are the exact roles you need assigned, depending on your target:
- Target resource (Azure SQL Managed Instance, SQL Server on Azure VM, or Azure SQL Database):
Contributorrole - Resource Group containing the target:
Readerrole - Storage Account (if you're uploading backups from an SMB network share, not required for Azure SQL Database migrations):
Contributorrole on the Storage Account
To check and assign these in the portal, navigate to each resource, click Access control (IAM) in the left menu, then click Role assignments. Look for your user account or the service principal you're using. If the needed role is missing, click + Add > Add role assignment, select the correct role, and assign it to your account.
For a faster check across all resources using PowerShell:
# List role assignments for your account on a specific resource group
Get-AzRoleAssignment -ResourceGroupName "your-rg-name" -SignInName "your@email.com"After confirming the roles are in place, retry your migration. If it was an RBAC issue, the migration should now progress past the authorization stage. You'll see the migration status move from Pending to Running in the Azure DMS blade under your project.
One of the most valuable, and most skipped, steps in the Azure DMS workflow is running the pre-migration assessment. Azure DMS uses the same underlying assessment engine as Azure Arc readiness assessments to scan your source SQL Server and identify anything that will block or complicate the migration. If you skip this and jump straight to migrating, you might get halfway through and hit a compatibility failure that could have been caught and fixed beforehand.
You can trigger the assessment through PowerShell using the Azure DataMigration Service Module. First, make sure you have the module installed:
Install-Module -Name Az.DataMigration -AllowClobber -ForceThen run a SQL Server assessment against your source instance:
Get-AzDataMigrationAssessment `
-ConnectionString "Data Source=your-sql-server;Initial Catalog=master;Integrated Security=True" `
-OutputFolder "C:\DMS\Assessment" `
-OverwriteThe output folder will contain a JSON report with findings. Open it and look for items flagged as BreakingChange, those are migration blockers. Common ones include deprecated SQL features your schema uses, linked server dependencies, and FILESTREAM data. Each finding includes a recommended remediation action.
Fix the blocking items in your source database before proceeding. For items flagged as Warning rather than BreakingChange, you can often proceed with the migration and address them post-migration, but document them so nothing gets missed. Once your assessment report shows no blocking issues, you're ready to actually configure the migration.
This is a decision that has downstream consequences, you can't easily switch mid-migration. Getting it wrong either means unnecessary downtime or a migration setup that doesn't actually support the mode you want.
Here's the real-world breakdown: offline migrations take a snapshot of your source database, stop writes, and move the data. Your source database is effectively frozen during this process. This is fine for lower-traffic databases or when you have a maintenance window. Online migrations keep your source database running and accepting writes throughout the migration, replicating changes continuously until you're ready to cut over, giving you minimal downtime.
Not every migration scenario supports both modes. According to the official Azure DMS feature matrix, here's what's currently supported:
- Azure SQL Database: Offline only
- Azure SQL Managed Instance: Both online and offline
- SQL Server on Azure Virtual Machines: Both online and offline
If you're planning an online migration to Azure SQL Database, you'll need to look at a different tooling path, Azure DMS doesn't support online mode for that target. This is a common source of confusion and something the portal error messages don't spell out clearly.
To configure your migration mode in the portal, when you create a new migration project in Azure DMS, you'll see a Migration mode dropdown. Select Online migration or Offline migration based on the above. If online mode is grayed out for your selected target, that confirms it's not supported for that combination. Plan your application downtime window accordingly for offline migrations.
This is where Azure DMS migrations to hybrid or on-premises SQL Server sources get complicated. Azure DMS needs to reach your source SQL Server to read data, and if that server is on-premises, behind a firewall, or in a private network without direct Azure connectivity, you need to configure a self-hosted integration runtime (SHIR) to give Azure DMS its own compute access to the source.
The self-hosted integration runtime is essentially a Windows service you install on a machine that has line-of-sight to your source SQL Server. Here's how to set it up:
- In the Azure portal, navigate to your Azure Data Factory or Integration Runtime resource.
- Under Connections > Integration runtimes, click + New.
- Select Self-Hosted and give it a name.
- Download the integration runtime installer from the provided link and run it on a machine in your on-premises network (Windows Server 2016 or later recommended).
- During installation, paste in the authentication key shown in the portal to register the runtime.
Once the SHIR shows as Running in the portal, go back to your Azure DMS migration configuration and select it as your integration runtime. This routes migration traffic from Azure through your on-premises machine to your SQL Server rather than trying to reach it directly over the public internet.
# Verify your SHIR status using PowerShell
Get-AzDataFactoryV2IntegrationRuntime `
-ResourceGroupName "your-rg" `
-DataFactoryName "your-adf" `
-Name "your-shir-name" | Select-Object Name, StateIf the SHIR shows as Offline or Limited, check that the Windows service named DIAHostService is running on your on-premises machine and that outbound port 443 is open to Azure endpoints.
If you're migrating a single database, the portal is fine. But if you're moving dozens of databases across multiple SQL Server instances, which is the reality in most enterprise SQL Server consolidation projects, doing it manually through the portal will take forever and introduce human error. Azure DMS has solid automation support through PowerShell and the Azure CLI, and this is the way to do it at scale.
First, make sure you have the Az.DataMigration module installed and you're authenticated:
Install-Module Az.DataMigration -Force
Connect-AzAccount
Set-AzContext -SubscriptionId "your-subscription-id"Here's a minimal script to kick off a SQL Server to Azure SQL Managed Instance migration using an Azure Storage backup location. Adjust the parameter values to match your environment:
$migrationService = New-AzDataMigrationToSqlManagedInstance `
-ResourceGroupName "your-rg" `
-ManagedInstanceName "your-sql-mi" `
-TargetDbName "YourDatabaseName" `
-Kind "SqlMI" `
-Scope "/subscriptions/your-sub-id/resourceGroups/your-rg/providers/Microsoft.Sql/managedInstances/your-sql-mi" `
-MigrationService "/subscriptions/your-sub-id/resourceGroups/your-rg/providers/Microsoft.DataMigration/SqlMigrationServices/your-dms" `
-StorageAccountResourceId "/subscriptions/your-sub-id/resourceGroups/your-rg/providers/Microsoft.Storage/storageAccounts/your-storage" `
-StorageAccountKey "your-storage-key" `
-BlobContainerName "backups" `
-SourceSqlConnectionAuthentication "WindowsAuthentication" `
-SourceSqlConnectionDataSource "your-source-server" `
-SourceDatabaseName "YourSourceDatabase" `
-MigrationMode "Offline"For migrating multiple databases, wrap this in a foreach loop over a list of database names. The Azure DMS team has published end-to-end multi-database automation sample scripts in the official documentation, search for "End-to-End migration automation for multiple databases" in the Azure DMS PowerShell reference section. Those scripts handle status polling and failure detection, which you'll want for any production migration run.
Monitor migration status programmatically:
Get-AzDataMigrationToSqlManagedInstance `
-ResourceGroupName "your-rg" `
-ManagedInstanceName "your-sql-mi" `
-TargetDbName "YourDatabaseName" | Select-Object MigrationStatus, CurrentRestoringFilenameWhen you see MigrationStatus return ReadyForCutover (for online migrations), that's your signal to initiate the cutover step and complete the migration.
Advanced Troubleshooting
If you've worked through the five steps above and Azure Database Migration Service is still giving you trouble, the issue is likely sitting in one of a few deeper layers: network private endpoints, schema migration failures, TDE limitations, or the tracking resource creation failing in ways that block the entire workflow.
Private Endpoint Connectivity Failures
Azure DMS supports private endpoints for connecting to both source and target, which is essential in enterprise environments where public internet access to your databases is blocked. If you're getting connection timeout errors even after confirming firewall rules are correct, private endpoints might be misconfigured.
Check that your private endpoint DNS resolution is working properly. In many enterprise setups, custom DNS servers don't automatically forward Azure private DNS zone queries. Your Azure private DNS zones for SQL (privatelink.database.windows.net for Azure SQL Database, privatelink.database.windows.net for Managed Instance) need to be linked to the virtual network your DMS service lives in.
# Check your private DNS zone VNet links
Get-AzPrivateDnsVirtualNetworkLink `
-ResourceGroupName "your-rg" `
-ZoneName "privatelink.database.windows.net"Schema Migration Failures
Azure DMS supports schema migration as part of the migration process. When schema migration fails, it usually surfaces as a "Schema migration failed" status in the migration activity log within the portal. Navigate to your migration project, click on the database name, and look at the Database migration details pane, there's a schema migration tab that shows the specific object that failed. Common culprits are unsupported object types, circular dependencies, and object names that conflict with reserved words in the target platform.
TDE-Encrypted Databases: Know the Limitation
This one is documented but not well-publicized: Azure DMS does not support migrating databases encrypted with Transparent Data Encryption (TDE). If your source database has TDE enabled, Azure DMS will either fail during the migration or during the assessment phase. You'll need to either decrypt the source database before migration, or use an alternative migration path (BACPAC export/import for smaller databases, or Azure SQL Database managed backup restore for TDE-enabled databases).
Login Migration: What's Not There Yet
If you're expecting Azure DMS to migrate SQL Server logins along with your database, note that login migration is listed as "No" in the current Azure portal version's feature matrix. You'll need to script out your logins separately using a tool like SQL Server Management Studio (SSMS) > Tasks > Generate Scripts, or using this system stored procedure approach:
-- Run this on your source SQL Server to script all logins
EXEC sp_help_revloginTake that output and run it on your target after the database migration is complete.
Tracking Resource Creation Errors in Restricted Subscriptions
In environments with Azure Policy restrictions, particularly subscriptions managed by enterprise governance teams, the Azure DMS tracking resource creation often fails even after you manually register the Microsoft.AzureArcData provider. This happens when a policy definition blocks the creation of Azure Arc-related resources. Work with your Azure governance team to confirm there are no deny assignments or policy effects blocking the Microsoft.AzureArcData/sqlServerInstances resource type in your subscription.
Prevention & Best Practices
The teams that run smooth Azure Database Migration Service projects, the ones where the migration completes cleanly and nobody's paged at 2am, all do the same things before they kick off the actual migration. None of it is complicated. It's mostly about front-loading the validation work so you're not discovering problems after you've started moving data.
First: always run the pre-migration assessment at least a week before your migration window. Not the day before. You need time to actually fix what it finds. Feature parity gaps between SQL Server and Azure SQL targets, things like SQL Server Agent jobs, linked servers, deprecated compatibility levels, need time to remediate or document as post-migration tasks.
Second: test your network connectivity from the Azure DMS service to both your source and target before migration day. Use the Azure DMS connectivity test built into the portal (it's on the migration configuration screen, look for "Test connection" next to your source connection string). Don't assume firewall rules are correct until you've verified them with an actual connection test.
Third: for online migrations, monitor the lag between source and target during the continuous sync phase. If replication lag grows instead of staying stable, your migration won't complete cleanly. The Azure DMS portal shows lag metrics in the migration monitoring view, watch for it to stabilize at near-zero before initiating cutover.
Fourth: script your post-migration steps before migration day. Logins, SQL Server Agent jobs, linked servers, and any app connection strings that need updating, have all of that ready to execute the moment the migration completes. The faster you switch over application traffic, the smaller your downtime window for online migrations.
- Register
Microsoft.AzureArcDataon every subscription that will use Azure DMS, do it as part of your standard subscription provisioning checklist. - Pre-assign RBAC roles to migration service accounts with a least-privilege policy document, Contributor on targets, Reader on resource groups, Storage Contributor when using SMB backups.
- Keep a test Azure SQL Managed Instance in a non-prod environment to validate your migration scripts before running them against production databases.
- Check regional availability of Azure DMS before choosing your target region, not all Azure regions support every DMS migration scenario, and this can surprise you late in planning.
Frequently Asked Questions
What is Azure Database Migration Service and what databases does it support?
Azure Database Migration Service is a fully managed Azure service that moves databases from various sources, SQL Server, PostgreSQL, MySQL, MongoDB, into Azure data platforms like Azure SQL Database, Azure SQL Managed Instance, SQL Server on Azure VMs, Azure DB for PostgreSQL, Azure DB for MySQL, and Azure Cosmos DB for MongoDB. You access it through the Azure portal, PowerShell, or Azure CLI. It handles the migration steps automatically once you've configured the source, target, and migration mode, taking advantage of Microsoft's best practices so you can trust the process rather than manually orchestrating every data movement step yourself.
Why does my Azure DMS migration fail with a "resource provider not registered" error?
This happens when your Azure subscription hasn't registered the Microsoft.AzureArcData resource provider, which Azure DMS needs to create its tracking resource. The service tries to auto-register it for you, but Azure Policy restrictions in enterprise subscriptions often block that auto-registration silently. The fix is to register it manually: run Register-AzResourceProvider -ProviderNamespace Microsoft.AzureArcData in PowerShell, or go to Azure portal > Subscriptions > Resource providers > search "AzureArcData" > click Register. Wait about 90 seconds for it to show as Registered, then retry your migration.
Can I migrate a TDE-encrypted SQL Server database using Azure DMS?
No, TDE (Transparent Data Encryption) encrypted database migration is not supported by Azure DMS in its current Azure portal version. This is a documented limitation. If your source database has TDE enabled, you'll need to either decrypt it before migration, export it as a BACPAC file and import it to the target (works for smaller databases), or use the native backup-and-restore path for Azure SQL Managed Instance which does support TDE certificates. Make sure to check your source databases for TDE during your pre-migration assessment so this doesn't surprise you on migration day.
What's the difference between online and offline migration in Azure DMS, and which should I use?
Offline migration takes a point-in-time backup of your source database, transfers it to the target, and requires your application to be down for the entire duration. Online migration keeps your source running and continuously replicates changes to the target until you initiate a cutover, resulting in minimal downtime measured in seconds or minutes rather than hours. The right choice depends on your downtime tolerance and target platform: Azure SQL Database only supports offline migration through Azure DMS, while Azure SQL Managed Instance and SQL Server on Azure VMs support both modes. For business-critical databases with tight SLAs, online migration to SQL Managed Instance is usually the right call.
Does Azure Database Migration Service migrate SQL Server logins along with the database?
Not in the current Azure portal version, login migration is listed as an unsupported feature. Your database schema and data move over, but SQL logins stay behind. You need to handle login migration separately: use the sp_help_revlogin stored procedure on your source SQL Server to generate a script of all logins, then run that script on the target after the database migration completes. Alternatively, SSMS has a "Generate Scripts" wizard under Tasks that can export logins. Plan this as a post-migration task and keep the scripts ready to run the moment your database is live on the target.
How do I migrate multiple databases at once using Azure DMS automation?
Azure DMS has full PowerShell and Azure CLI support for automating migrations at scale. Install the Az.DataMigration PowerShell module, then use cmdlets like New-AzDataMigrationToSqlManagedInstance or New-AzDataMigrationToSqlDb inside a loop over your list of database names. Microsoft publishes official sample scripts for end-to-end multi-database migration automation, search the Azure DMS documentation for "End-to-End migration automation for multiple databases" to find them. These scripts include status polling so you can monitor each database's progress without watching the portal manually. For large estates with databases across multiple SQL Server instances, this automation path is far more reliable than the portal.