Migration Report Shows Failed Unsupported Characters: Root Cause and Fix

When you migrate files to SharePoint or OneDrive, the migration report may show items that failed due to unsupported characters. This error occurs because SharePoint and OneDrive do not accept certain characters in file or folder names. The characters include ~, #, %, &, , {, }, \, :, <, >, ?, /, |, and ". This article explains why the error happens and gives you clear steps to fix the names before or after the migration.

• ~ tilde
• # number sign
• % percent
• & ampersand
• asterisk
• { left curly bracket
• } right curly bracket
• \ backslash
• : colon
• < less-than sign
• > greater-than sign
• ? question mark
• / forward slash
• | vertical bar
• " double quotation mark

When you run a migration, the SharePoint Migration Tool (SPMT) or any third-party tool scans each file name. If it finds any of these characters, it logs the file as a failure in the migration report. The root cause is strictly a naming constraint in SharePoint. The destination library cannot create a file with those characters, so the migration skips or fails the item.

The migration report typically shows the full path and the specific character that caused the failure. You must rename the file or folder before you can migrate it successfully.

Steps to Fix Unsupported Characters Before or After Migration

You can fix the file names before you start the migration or after the report shows failures. The following methods work for on-premises files, local network drives, or files already staged in a temporary location.

Method 1: Use the SharePoint Migration Tool Pre-Scan

1. Download and open SPMT
   Go to the Microsoft 365 admin center and download the SharePoint Migration Tool. Install and open it on the computer that has access to the source files.
2. Choose your source
   Select the source location: a local folder, a network share, or an on-premises SharePoint farm. Enter the path to the folder that contains the files you want to migrate.
3. Run a scan only
   In the SPMT interface, choose the option to scan the files without migrating. This generates a report that lists all files with unsupported characters. The report shows the full file path and the character that is not allowed.
4. Review the scan report
   Open the CSV file that SPMT creates. Look for the column named "Issue" or "FailureReason." Each row with an unsupported character will show the specific character, for example, "Character '#' is not allowed."
5. Rename the files manually or with a script
   Use Method 2 or Method 3 below to rename the files listed in the scan report. After renaming, run a new scan to confirm no issues remain.

Method 2: Use a PowerShell Script to Replace Unsupported Characters

1. Open PowerShell as administrator
   Press the Windows key, type PowerShell, right-click Windows PowerShell, and select Run as administrator.
2. Set the folder path
   Run this command to define the folder that contains your files. Replace C:\SourceFiles with your actual path.
   $path = "C:\SourceFiles"
3. Run the rename script
   Copy and paste the following script into PowerShell. It replaces all unsupported characters with an underscore _.
   Get-ChildItem -Path $path -Recurse | Where-Object { $_.Name -match '[~#%&{}:<>?/|"\]' } | Rename-Item -NewName { $_.Name -replace '[~#%&{}:<>?/|"\\]', '_' } -ErrorAction SilentlyContinue
4. Verify the changes
   Run Get-ChildItem -Path $path -Recurse | Where-Object { $_.Name -match '[~#%&{}:<>?/|"\\]' } to confirm no unsupported characters remain. The output should be empty.