PowerShell Migration Script Error – Troubleshooting Guide
Using PowerShell scripts for SharePoint migration is a common approach for automating database migrations, site collection transfers, or bulk content moves. However, errors can occur due to incorrect permissions, syntax issues, missing modules, or environment inconsistencies. Below is a step-by-step troubleshooting guide to identify and fix PowerShell migration script errors.
Step 1: Identify the Type of Migration Script
Before troubleshooting, determine what type of migration script you are using:
- Content Database Migration (
Mount-SPContentDatabase) - Site Collection Migration (
Export-SPWeb/Import-SPWeb) - Document Library Migration (
Move-PnPFile,Get-PnPListItem) - SharePoint Online Migration (
SharePointPnPPowerShellOnline,Invoke-SPOSiteSwap)
Understanding the script type helps in pinpointing the cause of errors.
Step 2: Check PowerShell Script Syntax
Even a small syntax error can break the script. Before running, check:
✅ Missing or extra brackets, quotes, or commas
✅ Incorrect cmdlet names
✅ Wrong parameters or typos
Use this command to validate a script before execution:
Test-Path "C:\Scripts\MyMigrationScript.ps1"
Step 3: Run PowerShell as Administrator
Many SharePoint migration scripts require elevated permissions.
- Right-click Windows PowerShell → Select Run as Administrator.
- Try running the script again.
Step 4: Ensure the Required PowerShell Modules Are Installed
Depending on the migration type, different PowerShell modules are required.
For SharePoint On-Premises (2013/2016/2019)
Check if the SharePoint module is available:
Get-Module -ListAvailable | Where-Object { $_.Name -like "*SharePoint*" }
If missing, import it manually:
Add-PSSnapin Microsoft.SharePoint.PowerShell
If the snap-in is missing, reinstall SharePoint Management Shell.
For SharePoint Online (SPO) Migration
Verify the PnP PowerShell module:
Get-Module -Name PnP.PowerShell -ListAvailable
If missing, install it:
Install-Module -Name PnP.PowerShell -Scope CurrentUser -AllowClobber
Step 5: Verify PowerShell Execution Policy
If you see “script cannot be loaded because running scripts is disabled”, change the execution policy:
Set-ExecutionPolicy Unrestricted -Scope Process
Alternatively, allow signed scripts:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Step 6: Check for Insufficient Permissions
Errors often occur when the PowerShell script lacks the necessary permissions.
For SharePoint On-Premises
Ensure the Farm Administrator account is used. Check permissions using:
whoami
If permission is denied, run:
Start-Process PowerShell -Verb RunAs
For SharePoint Online
Make sure you connect as a Global Admin:
Connect-PnPOnline -Url "https://yourtenant-admin.sharepoint.com" -UseWebLogin
If you get access denied, check admin permissions in Microsoft 365 Admin Center.
Step 7: Debug and Log Errors
If the script fails, enable detailed logging to capture errors.
Method 1: Use Try-Catch Blocks for Error Handling
Modify the script to capture errors:
Try {
Import-SPWeb -Identity "https://yourwebapp/sites/mysite" -Path "C:\Backup\mysite.cmp"
}
Catch {
Write-Host "Error: $($_.Exception.Message)" -ForegroundColor Red
}
Method 2: Redirect Output to a Log File
.\MyMigrationScript.ps1 > C:\Logs\migrationlog.txt 2>&1
Check migrationlog.txt for errors.
Step 8: Check Network and Connectivity Issues
For SharePoint Online migrations, ensure there is no network blocking:
- Test Connectivity to SharePoint Online:
Test-NetConnection yourtenant.sharepoint.com -Port 443 - Ensure Proxy or Firewall Rules Do Not Block the Script.
Step 9: Verify Database and Site Readiness (For On-Premises Migrations)
If migrating content databases, ensure the database is restored and in a correct state before attaching it:
Mount-SPContentDatabase -Name "WSS_Content" -DatabaseServer "SQLServerName" -WebApplication "http://yourwebapp"
If it fails, check SQL Server logs for database connection issues.
Step 10: Test the Script on a Small Dataset
If the script affects a large dataset, test it on a small subset before full migration.
Example: Migrating only 10 items instead of the whole list:
Get-PnPListItem -List "Documents" -PageSize 10
Step 11: Update and Rerun the Script
If all else fails:
- Update PowerShell and all modules (
Update-Module PnP.PowerShell) - Restart the system and rerun the script
- Manually execute commands from the script step-by-step to find the exact failing line
Final Recommendations
✅ Check PowerShell syntax before execution.
✅ Ensure the correct PowerShell modules are installed.
✅ Run PowerShell with administrator rights.
✅ Enable detailed error logging.
✅ Test migration scripts on small data sets first.
By following these steps, you can effectively troubleshoot PowerShell migration script errors in SharePoint.
Would you like me to help debug a specific PowerShell script?