How to Troubleshoot Migration Report Shows Failed Unsupported Characters

When you run a SharePoint migration using the SharePoint Migration Tool (SPMT) or the Migration API, the migration report may show items as failed due to unsupported characters in file names, folder names, or metadata. SharePoint Online enforces strict naming rules that reject characters like #, %, &, {, ~, and trailing spaces. These failures can stop your migration from completing or cause partial data loss. This article explains why unsupported characters cause failures, how to identify them in the migration report, and the exact steps to fix the file names so your migration can succeed.

Why Unsupported Characters Cause Migration Failures

SharePoint Online uses the Windows file system naming conventions plus additional restrictions for web-based access. When a file or folder name contains a character that is not allowed, the SharePoint Migration Tool cannot create the item in the destination library. The migration engine logs the file as Failed with an error code like UnsupportedFileNameCharacters or InvalidFolderName.

The complete list of unsupported characters in SharePoint Online file and folder names includes:

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

These restrictions apply to file names, folder names, and metadata fields such as title or description. The migration tool does not automatically rename files. You must fix the names before or after the migration attempt.

Steps to Identify and Fix Unsupported Characters in the Migration Report

1. Open the Migration Report
   After a migration job completes, open the SharePoint Migration Tool. Go to Migration Manager and select the job that failed. Click View Report to download the CSV file. The report contains columns for Source Path, Destination Path, Status, and Error. Filter the Status column to show only Failed rows.
2. Identify the Unsupported Characters
   In the CSV report, look at the Error column. If the error message contains UnsupportedFileNameCharacters or InvalidFolderName, note the full source path. Copy the file or folder name into a text editor. Use the character list above to find the offending character. Common culprits are # in file names from version numbers, & in project names, and trailing spaces from user input.
3. Rename the Files or Folders on the Source
   On your local file server or network share, navigate to the source folder. Rename each file or folder that contains unsupported characters. Replace each invalid character with a valid alternative. For example, replace # with No, replace & with and, and remove trailing spaces. Keep the name short and readable. Do not use characters that are still invalid.
4. Use PowerShell to Scan and Rename Automatically
   If you have many files, use a PowerShell script to find and rename them. Open PowerShell as administrator and run this script that replaces invalid characters with a hyphen:

   
Get-ChildItem -Path "C:\SourceFolder\" -Recurse | Where-Object { $_.Name -match '[~"#%&:<>?/\\{|} ]' } | ForEach-Object {
  $newName = $_.Name -replace '[~"#%&:<>?/\\{|} ]', '-';
  Rename-Item -Path $_.FullName -NewName $newName
}

   Replace C:\SourceFolder with your actual source path. This script replaces any invalid character with a hyphen. Test it on a small folder first.

5. Re-run the Migration Job
   After renaming the files, go back to the SharePoint Migration Tool. Select the same source and destination. The tool will scan the source again. Since the names are now valid, the migration should complete without the unsupported character error. Monitor the new report to confirm all items pass.
6. Verify the Files in SharePoint
   After the migration finishes, open the SharePoint document library in a browser. Check that all files appear with the new names. Open a few files to confirm the content is intact. If you used a script, verify that no file names were truncated or duplicated.

If the Migration Still Shows Failures After Renaming

"The file name contains a trailing period or space"

SharePoint does not allow file names that end with a period or a space. For example, Report..docx or Draft .docx. These characters are invisible in many file explorers. To fix this, use PowerShell to remove trailing periods and spaces. The script above will replace spaces with hyphens but will not remove trailing periods. Add this line after the rename command:

Rename-Item -Path $_.FullName -NewName ($_.BaseName.TrimEnd('. ') + $_.Extension)

"The file name is too long"

SharePoint Online has a maximum path length of 400 characters. If your file path (including folder names) exceeds this limit, the migration fails. The error message may say PathTooLong. Shorten folder names or remove unnecessary nested folders. Move deep files closer to the root of the library.

"The migration report shows no errors but some files are missing"

If the report says all items succeeded but files are missing, check the Skipped column in the CSV report. Files may be skipped if the destination already has a file with the same name. Delete the existing file or use the Overwrite option in the migration settings.

Manual Fix vs Automated Fix: Key Differences

Item	Manual Fix	Automated Fix with PowerShell
Time required	High for many files	Low after script setup
Risk of human error	High	Low if script is tested
Control over new names	Full control per file	Uses a consistent replacement rule
Best for	Few files with complex naming needs	Hundreds or thousands of files

After fixing all unsupported characters, your migration report should show zero failures for that category. Re-run the migration job for the corrected files. If you still see failures, check for other errors such as duplicate names or permission issues. The SharePoint Migration Tool logs every error with a specific code, which you can look up in Microsoft documentation. Use the Export report feature to keep a record of successful migrations for auditing.