Clean File Names Before SharePoint Migration: Practical Checklist for SharePoint Owners

You are preparing to move files to SharePoint and want to avoid sync errors, broken links, and access problems. Many file names that work fine on a local drive or network share contain characters, lengths, or patterns that SharePoint rejects. This article provides a practical checklist to clean file names before migration so your content moves without errors and stays accessible.

Why File Names Cause Problems in SharePoint

SharePoint uses Windows file system rules plus its own URL-based restrictions. When you upload a file, SharePoint creates a URL from the site address, library name, folder path, and file name. If any part of that path contains characters that SharePoint cannot encode correctly, the file fails to upload or sync.

The most common root cause is the presence of reserved characters in file names. Characters such as #, %, &, and + have special meaning in URLs. When SharePoint tries to create a URL containing these characters, it either blocks the file or produces a URL that breaks when shared or synced.

Another frequent issue is file path length. SharePoint limits the total URL path to 400 characters. This includes the site name, library name, all folder names, and the file name. A deep folder structure with long names can easily exceed this limit, causing upload failures and sync errors.

File names that start or end with a period or space also cause problems. SharePoint trims trailing spaces and periods, which can lead to duplicate file names or unexpected renaming.

Checklist to Clean File Names Before Migration

1. Remove invalid characters from file names
   Scan all file names for these blocked characters: ~ # % & : < > ? / \ { } |. Replace each with a hyphen or underscore. For example, change Q3%20Report to Q3-20-Report. Use a PowerShell script or a file renaming tool to automate this across thousands of files.
2. Shorten file paths to under 400 characters
   Calculate the full URL path length: site URL + library name + folder path + file name. If the total exceeds 400 characters, shorten folder names or flatten the folder structure. Move files from nested folders to a shallower hierarchy.
3. Replace spaces with hyphens or underscores
   Spaces in file names work in SharePoint but cause issues during sync with OneDrive and when sharing links. Replace spaces with hyphens for readability or underscores for machine processing. For example, change Meeting Notes.docx to Meeting-Notes.docx.
4. Remove leading and trailing periods and spaces
   File names that start or end with a period or space are not allowed. Rename .hidden-file to hidden-file and report .docx to report.docx.
5. Standardize file name casing
   SharePoint is case-insensitive but preserves case. To avoid confusion, use consistent casing. A common convention is PascalCase for multi-word names: QuarterlyReport.docx instead of quarterly_report.docx.
6. Remove special characters that break sync
   Characters like @, !, ^, ~, and $ are technically allowed but cause sync errors in OneDrive. Remove them or replace with hyphens.
7. Check for duplicate file names after renaming
   After renaming files, you may end up with two files that now have the same name. For example, Q3 Report and Q3-Report both become Q3-Report. Run a duplicate check and rename conflicting files with a unique identifier like a date or version number.
8. Test a sample batch before full migration
   Select 50 to 100 files that represent the most complex naming patterns in your source. Upload them to a test SharePoint library. Verify that all files upload, sync, and open correctly. Fix any errors before migrating the full set.

What Happens If You Skip File Name Cleaning

Skipping file name cleaning leads to several problems that appear during or after migration.

Files fail to upload during migration

Migration tools like SharePoint Migration Tool or ShareGate report errors for files with invalid characters. Each failed file requires manual intervention, slowing down the entire migration. You may need to restart the migration after fixing names.

Sync errors in OneDrive

Files that contain characters like # or % will upload but fail to sync with OneDrive. Users see error messages like Sync error: file name contains invalid characters. They cannot access the file offline.

Broken links in documents and emails

When a file name contains a # character, SharePoint encodes it as %23 in the URL. Any link that points to the original URL with # breaks. Users clicking the link see a 404 error.

Search and metadata issues

File names with special characters may not be indexed correctly by SharePoint search. Users searching for a file that contains & in its name may not find it. Metadata extraction from file names also fails when special characters are present.

File Name Rules: Local Drive vs SharePoint

Item	Local Drive (Windows)	SharePoint / OneDrive
Maximum file name length	255 characters	255 characters (file name only)
Maximum URL path length	Not applicable	400 characters (site + library + path + file)
Invalid characters	\ / : ? < > |	~ # % & : < > ? / \ { } | plus leading/trailing periods and spaces
Case sensitivity	Case-insensitive	Case-insensitive, case-preserving
Allowed spaces	Yes	Yes but cause sync and link issues

The key difference is the 400-character URL path limit and the additional invalid characters in SharePoint. A file that works perfectly on a local drive may fail in SharePoint because of these extra restrictions.

After you clean all file names and paths, run a final scan with a tool like the SharePoint Migration Assessment Tool. This tool checks for naming issues and generates a report of files that need attention. Apply the checklist to your source files before starting the migration tool. Your files will move cleanly, sync without errors, and remain accessible to all users.