SharePoint File Naming Errors

When uploading or syncing files to SharePoint Online, you may see errors like “This file name contains invalid characters”, “The file path is too long”, or sync status badges showing red indicators. These issues prevent files from syncing to the cloud and block other users from accessing them.

This guide outlines SharePoint’s file naming constraints, explains path length restrictions, and provides terminal commands and scripts to find and fix non-compliant filenames on Windows and macOS.

1. Understand SharePoint File Naming Errors

SharePoint Online and OneDrive have strict requirements for character usage, path depth, and name strings. Sync errors occur due to three main factors:

• Forbidden Characters: Names containing special characters (e.g., *, :, <, >, ?, /, \, |, ") will trigger sync errors.
• Reserved Names: Windows-reserved filenames like CON, PRN, AUX, NUL, COM1 through COM9, and LPT1 through LPT9 cannot be synced to SharePoint.
• Leading or Trailing Spaces: File or folder names that begin or end with a space or end with a period (e.g., Document .docx or Folder) are rejected by the sync engine.
• Path Length Limits (MAX_PATH):
  • SharePoint Online limits the total URL length (including domain, site, library, subfolders, and file name) to 400 characters.
  • Windows desktop clients default to a 260-character path limit (MAX_PATH), causing OneDrive to stop syncing if deeply nested folder structures exceed this limit.

2. Invalid Characters and File Path Length Limits

Before running cleanups, ensure you understand the boundaries:

• Characters blocked in all scenarios: *, :, <, >, ?, /, \, |, "
• Characters that cause issues with legacy apps: #, %, {, }, ~, &
• Leading/Trailing Whitespace: Any space at the very start or end of a name.
• Folder Name Limits: Cannot end with a period ..

Step 1: Scan for Invalid Characters and Long Paths

Run the following PowerShell script in PowerShell (replace the path with your synced SharePoint folder):

# Set the root folder of your synced SharePoint library
$SyncFolder = "$USERPROFILE\SharePoint"

# 1. Find files with invalid characters
Write-Host "Searching for files with invalid characters..." -ForegroundColor Yellow
Get-ChildItem -Path $SyncFolder -Recurse | Where-Object { $_.Name -match '[~"#%&*:<>\?/\\{|}~]' } | Select-Object Name, FullName

# 2. Find files/folders ending with a space or period
Write-Host "Searching for trailing spaces or periods..." -ForegroundColor Yellow
Get-ChildItem -Path $SyncFolder -Recurse | Where-Object { $_.Name -match '\s+$|\.+$' } | Select-Object Name, FullName

# 3. Find files exceeding Windows MAX_PATH (260 characters)
Write-Host "Searching for files exceeding 240 characters..." -ForegroundColor Yellow
Get-ChildItem -Path $SyncFolder -Recurse | Where-Object { $_.FullName.Length -gt 240 } | Select-Object @{Name="Length";Expression={$_.FullName.Length}}, FullName

$SyncFolder = "$USERPROFILE\SharePoint"

# Execute sanitization
Get-ChildItem -Path $SyncFolder -Recurse | ForEach-Object {
    $OldName = $_.Name
    # Replace forbidden characters with underscore
    $NewName = $OldName -replace '[~"#%&*:<>\?/\\{|}]', '_'
    # Remove leading/trailing spaces or trailing periods
    $NewName = $NewName.Trim().TrimEnd('.')
    
    if ($OldName -ne $NewName) {
        $NewFullName = Join-Path $_.Parent.FullName $NewName
        Write-Host "Renaming: $OldName -> $NewName" -ForegroundColor Green
        Rename-Item -Path $_.FullName -NewName $NewName -ErrorAction SilentlyContinue
    }
}

# Define your local SharePoint path
SYNC_DIR="$HOME/Library/CloudStorage"

echo "=== Files containing forbidden characters ==="
find "$SYNC_DIR" -type f -name '*[*:<>\?|\\"]*' 

echo "=== Files with trailing spaces ==="
find "$SYNC_DIR" -type f -name "* " 

echo "=== Path lengths exceeding 240 characters ==="
find "$SYNC_DIR" | awk 'length($0) > 240'

# Navigate to the sync directory
cd "$HOME/Library/CloudStorage"

# Find and rename files with invalid characters using a loop
find . -depth -name '*[*:<>\?|\\"]*' | while read -r file; do
    dir=$(dirname "$file")
    base=$(basename "$file")
    # Replace forbidden chars with hyphen
    new_base=$(echo "$base" | tr '*:<>?|\\"' '-')
    # Trim leading/trailing spaces
    new_base=$(echo "$new_base" | xargs)
    mv "$file" "$dir/$new_base"
    echo "Renamed: $base -> $new_base"
done

5. Summary Checklist for File Naming Errors