Clean File Names Before SharePoint Migration: SharePoint Admin Guide

When you migrate files to SharePoint, file names with unsupported characters or path lengths cause upload failures and sync errors. SharePoint imposes strict naming rules that differ from Windows file systems. This guide explains the specific characters and length limits SharePoint enforces and how to clean file names before migration. You will learn the exact rules, a step-by-step renaming process, and common pitfalls to avoid.

SharePoint File Naming Rules and Limitations

SharePoint Online and SharePoint Server apply the same set of naming rules for files and folders. These rules exist to ensure compatibility with web URLs, search indexing, and the underlying SQL database. Unlike Windows, SharePoint does not allow certain characters because they conflict with URL encoding or server-side processing.

Unsupported Characters in File and Folder Names

SharePoint does not allow the following characters anywhere in a file name or folder name:

• # (hash)
• % (percent)
• & (ampersand)
• (asterisk)
• { } (curly braces)
• ~ (tilde)
• \ (backslash)
• : (colon)
• < > (angle brackets)
• ? (question mark)
• / (forward slash)
• | (pipe)
• ” (double quote)

Additionally, SharePoint does not allow file or folder names to begin with a period (.) or contain a tilde (~) in the second character position, which is reserved for short file names. Names that end with a period or a space are also blocked.

Path Length Limit

SharePoint enforces a maximum path length of 400 characters. This includes the site URL, library name, folder path, and file name including the extension. For example, a file stored in a deeply nested folder structure may exceed this limit even if the file name itself is short. The Windows file system supports up to 260 characters by default, so files that work locally may fail after migration.

Reserved Names

SharePoint reserves certain names for system use. You cannot use the following names for files or folders: CON, PRN, AUX, NUL, COM1 through COM9, LPT1 through LPT9, and names with trailing periods or spaces. Windows also blocks these names, but a file migration from a non-Windows source may include them.

Steps to Clean File Names Before Migration

Use the following process to identify and rename files that violate SharePoint naming rules. Perform these steps on the source file share or local folder before you run any migration tool.

1. Scan the source folder for invalid characters
   Use a PowerShell script to list all files and folders that contain unsupported characters. Run this command in PowerShell: Get-ChildItem -Path "C:\SourceFolder" -Recurse | Where-Object { $_.Name -match '[#%&{}\\:<>?/|"~]' } | Select-Object FullName. This outputs every file and folder path that needs renaming.
2. Scan for path length violations
   Run a separate scan to find items where the full path exceeds 400 characters. Use: Get-ChildItem -Path "C:\SourceFolder" -Recurse | Where-Object { $_.FullName.Length -gt 400 } | Select-Object FullName. Note that SharePoint counts the destination site URL and library name as part of the path. Add 50 to 100 characters to account for the site URL prefix.
3. Rename files and folders using a script
   Create a PowerShell script that replaces each invalid character with an underscore or removes it. For example, replace # with _ and % with _ . Do not rename system files or files currently in use. Test the script on a small set of files first. A sample replacement command: $newName = $file.Name -replace '[#%&{}\\:<>?/|"~]', '_'. Then use Rename-Item -Path $file.FullName -NewName $newName.
4. Shorten deep folder paths
   For files that exceed the path length limit, restructure the folder hierarchy. Move files from deeply nested subfolders to a higher level. Alternatively, shorten folder names. After restructuring, run the path length scan again to confirm all paths are under 400 characters.
5. Remove trailing spaces and periods
   Use PowerShell to trim trailing spaces and trailing periods from file and folder names. SharePoint blocks names that end with a space or a period. Use: $newName = $file.Name.TrimEnd('. '). Then rename the item.
6. Check for reserved names
   Scan for files or folders named CON, PRN, AUX, NUL, COM1 through COM9, or LPT1 through LPT9. Rename any matches. Use: $reserved = @('CON','PRN','AUX','NUL','COM1','COM2','COM3','COM4','COM5','COM6','COM7','COM8','COM9','LPT1','LPT2','LPT3','LPT4','LPT5','LPT6','LPT7','LPT8','LPT9'). Then compare each file name without extension against this list.
7. Run a final validation
   After all renaming, run the scan scripts again to confirm zero violations. Document the changes in a log file for audit purposes. Then proceed with the SharePoint migration tool of your choice.

Common Issues When Cleaning File Names

File names begin with a period or tilde

Files that start with a period are hidden in Windows and are often configuration files. SharePoint blocks them. Rename the file to remove the leading period. For example, .htaccess becomes htaccess.txt. Files with a tilde in the second position, such as ~$temp.docx, are temporary Office files. Delete them if they are not needed.

Path length still exceeds 400 characters after shortening

If the folder structure is too deep, consider creating a flat library structure in SharePoint. Use metadata columns and views instead of nested folders. This reduces path length and improves search performance. For existing deep folders, move files to a new library with a shorter name.

Renamed files break application references

If other applications or scripts reference the original file names, renaming causes broken links. Update all references after renaming. Use a find-and-replace tool to update file paths in configuration files, databases, or documentation. Alternatively, keep a mapping table of old and new names.

Migration tool reports duplicate file names

After replacing invalid characters, multiple files may end up with the same name. For example, file#1.txt and file%1.txt both become file_1.txt. Before migration, resolve duplicates by appending a unique identifier, such as file_1_001.txt and file_1_002.txt. Scan for duplicates after renaming: Get-ChildItem -Recurse | Group-Object Name | Where-Object { $_.Count -gt 1 }.

Manual Cleaning vs Automated Cleaning: Key Differences

Item	Manual Cleaning	Automated Cleaning
Time required	Hours to days for large folders	Minutes to hours
Error rate	High due to human oversight	Low when script is tested
Duplicate detection	Difficult to spot manually	Script flags duplicates instantly
Audit trail	No automatic log	Script can output a CSV log
Cost	Free but labor-intensive	Free with PowerShell or low-cost third-party tools

For migrations involving more than 100 files, automated cleaning is strongly recommended. Manual cleaning is acceptable only for very small sets of files where you can verify each name individually.

You now have a repeatable process to clean file names before SharePoint migration. Run the PowerShell scan and rename steps as a pre-migration checklist item. After migration, verify that all files uploaded correctly by checking the library for any items with errors. For advanced protection, configure SharePoint to block file uploads with invalid names by using the library settings for file name validation.