Clean File Names Before SharePoint Migration: Practical Workflow for Business Users

When you migrate files to SharePoint, file names that contain special characters, excessive spaces, or long paths can cause sync errors, broken links, and search failures. SharePoint and OneDrive enforce strict naming rules that differ from local Windows file systems. This article explains the exact naming restrictions in SharePoint and provides a step-by-step workflow to clean file names before migration. You will learn how to identify problem files, rename them in bulk, and verify compliance to ensure a smooth migration.

Why SharePoint File Names Must Be Cleaned Before Migration

SharePoint stores files in a SQL Server content database and serves them via HTTP. The URL that SharePoint generates for each file includes the site path, library name, folder path, and file name. Characters that are valid in Windows file names — such as the ampersand (&), percent (%), or hash (#) — are either blocked or require URL encoding in SharePoint. If a file name contains a character that SharePoint cannot encode, the file upload fails or the file appears broken in the browser.

The official SharePoint naming rules block these characters: \ / : ? ” < > | . The tilde (~) and the number sign (#) are also problematic in certain positions. File names cannot start or end with a space or a period. The full path to a file — site URL plus library plus folder plus file name — must not exceed 400 characters. Windows allows paths up to 260 characters, so files that are valid on a local drive may violate SharePoint limits.

Another common issue is the presence of trailing spaces or periods in folder names. Windows Explorer hides trailing spaces visually, but SharePoint rejects them. When you copy a folder named “Reports ” (with a trailing space) to SharePoint, the folder fails to sync or creates duplicate entries.

List of Characters to Remove or Replace

The following characters are not allowed in SharePoint file names or folder names:

• Backslash \
• Forward slash /
• Colon :
• Asterisk
• Question mark ?
• Double quote “
• Less than <
• Greater than >
• Pipe |
• Tilde ~ (blocked at the start of a file name in some SharePoint versions)
• Number sign # (blocked at the start of a file name)
• Percent % (blocked at the start of a file name)
• Ampersand & (blocked at the start of a file name)
• Trailing space
• Trailing period

Step-by-Step Workflow to Clean File Names

This workflow assumes you have a local copy of the files you plan to migrate. Run these steps before you start the SharePoint Migration Tool or drag files into a SharePoint document library.

Step 1: Scan the Folder Structure for Violations

1. Open PowerShell as Administrator
   Press the Windows key, type PowerShell, right-click Windows PowerShell, and select Run as administrator.
2. Navigate to the root folder of your migration source
   Use the cd command to change to the folder that contains all files and subfolders. Example: cd “C:\Users\YourName\Documents\MigrationSource”
3. Run a scan to list all files with illegal characters
   Execute this PowerShell script to output a CSV file that lists every file and folder that violates SharePoint naming rules:
   Get-ChildItem -Recurse | Where-Object { $_.Name -match '[\\/:\\?"<>\|~#%]' -or $_.Name -match '\s$' -or $_.Name -match '\.$' } | Select-Object FullName, Name | Export-Csv -Path "violations.csv" -NoTypeInformation
   This script checks for all blocked characters, trailing spaces, and trailing periods. The CSV file appears in the current PowerShell directory.

Step 2: Review the Violation Report

1. Open the violations.csv file in Excel
   Double-click the file to open it. You will see two columns: FullName (the full path) and Name (the file or folder name that contains the violation).
2. Sort by the Name column
   This groups identical violations together. Look for patterns such as files with a colon or files ending with a space.
3. Decide on a replacement strategy for each character type
   Replace colons with a hyphen, replace ampersands with the word “and”, and remove trailing spaces entirely. Document your replacement rules so the renaming script is consistent.

Step 3: Run a Bulk Rename Script

1. Create a PowerShell script that replaces illegal characters
   Copy the following script into a text file and save it as CleanNames.ps1. Adjust the $sourcePath to match your migration source folder.
   $sourcePath = "C:\Users\YourName\Documents\MigrationSource"
Get-ChildItem -Path $sourcePath -Recurse -File | ForEach-Object {
$newName = $_.Name -replace '[\\/:\\?"<>\|]', '_'
$newName = $newName -replace '^[~#%]', '_'
$newName = $newName -replace '\s+$', ''
$newName = $newName -replace '\.+$', ''
if ($newName -ne $_.Name) {
Rename-Item -Path $_.FullName -NewName $newName -WhatIf
}
}
Get-ChildItem -Path $sourcePath -Recurse -Directory | ForEach-Object {
$newName = $_.Name -replace '[\\/:\\?"<>\|]', '_'
$newName = $newName -replace '^[~#%]', '_'
$newName = $newName -replace '\s+$', ''
$newName = $newName -replace '\.+$', ''
if ($newName -ne $_.Name) {
Rename-Item -Path $_.FullName -NewName $newName -WhatIf
}
}
   The -WhatIf parameter shows what would be renamed without actually renaming. Review the output.
2. Remove the -WhatIf parameter and run the script again
   After confirming the changes are correct, remove -WhatIf from both Rename-Item lines and run the script. The script renames all files and folders that contain illegal characters.

Step 4: Verify Path Length Compliance

1. Check the maximum path length in your source folder
   Run this PowerShell command to find the longest full path:
   Get-ChildItem -Path $sourcePath -Recurse | Where-Object { $_.FullName.Length -gt 400 } | Select-Object FullName, @{Name="Length";Expression={$_.FullName.Length}} | Sort-Object Length -Descending
2. Shorten paths that exceed 400 characters
   For each result, rename folders or files to reduce the total path length. A common approach is to shorten folder names or remove unnecessary nesting.

Step 5: Run a Final Validation Scan

1. Repeat the scan from Step 1
   Run the scan script again. Confirm that the violations.csv file is empty or contains only files you have chosen to exclude from migration.
2. Test a small batch of files in SharePoint
   Upload a few cleaned files to a test document library. Verify that you can open, edit, and sync the files without errors.

Common Mistakes When Cleaning File Names

Replacing Illegal Characters with a Space

A space is allowed in SharePoint file names, but it creates problems in URLs. SharePoint encodes spaces as %20, which makes URLs long and hard to read. Replace illegal characters with an underscore or a hyphen instead of a space.

Forgetting to Clean Folder Names

The PowerShell script above handles both files and folders. If you rename only files, folder names with illegal characters will still cause sync errors and broken navigation in SharePoint.

Using the SharePoint Migration Tool Without Pre-Cleaning

SPMT can rename files during migration by checking the option “Replace illegal characters.” However, this feature renames files only at the top level and does not fix folder names. Pre-cleaning gives you full control over the new names and prevents migration failures that require restarting the job.

Ignoring Duplicate File Names After Renaming

When you replace characters, two files with similar names may become identical. For example, “Report:2024” and “Report-2024” both become “Report_2024” after renaming. Before running the bulk rename, identify potential duplicates by running this PowerShell command:
Get-ChildItem -Path $sourcePath -Recurse -File | Group-Object Name | Where-Object { $_.Count -gt 1 }
If duplicates appear, add a suffix such as the date or a sequential number to one of the files.

Item	Windows File System	SharePoint Online
Maximum path length	260 characters (260 with long path support)	400 characters (site URL + library + folder + file name)
Blocked characters in file names	\ / : ? ” < > |	\ / : ? ” < > | ~ # % at start, trailing space, trailing period
Trailing space allowed	Yes (hidden in Explorer)	No
Trailing period allowed	Yes	No
Case sensitivity	Case-insensitive but case-preserving	Case-insensitive but case-preserving
URL encoding required	No	Yes, for characters like & and #

After you clean all file names, run the SharePoint Migration Tool with the validation option enabled. This confirms that every file meets SharePoint naming rules before the actual upload starts. If the tool reports any remaining violations, fix them in the source folder and rerun the validation.

For large migrations with thousands of files, schedule the cleaning script to run as a scheduled task the night before the migration. Test the script on a subset of files first to verify that the replacement rules produce readable names. Keep a log of all renamed files so you can map old names to new names if users need to locate specific documents after migration.