Our Thinking / Field Notes / The Guide

STEP-BY-STEP GUIDANCE / MICROSOFT 365 ADMINISTRATION - SHAREPOINT MIGRATION VALIDATION

How to Check a SharePoint Migration for Missing Files and Permissions

A sign-off routine for SharePoint Online migrations run with SPMT or Migration Manager: keep the reports, reconcile counts sensibly, triage failures, test access as real users and only then retire the source.

Start here

Download and keep the migration reports before they expire, then reconcile four numbers per task: scanned, filtered out, expected and migrated. Explain every gap by file name rather than by total. Separately, check permissions as ordinary users, because a migration can leave files either unreachable or more widely open than they were at the source. Keep the source untouched and read-only until the final incremental run is clean and each team has confirmed it can reach its own folders.

What this covers and what you need first

This guide is for a file share that has been moved into SharePoint Online with Microsoft's own tools: the SharePoint Migration Tool (SPMT) or Migration Manager in the SharePoint admin center. Third-party migration tools and tenant-to-tenant moves produce different reports. The method still applies, but the file names and column headings below won't.

The aim is not to prove that every byte arrived by comparing two totals. Totals rarely agree, and the reasons are usually dull. The aim is to show that every difference has an explanation, and that the right people can open the right folders while the wrong people cannot. The examples use a made-up share called Projects, with a restricted Finance folder inside it.

  • SharePoint admin rights, or site owner rights on the destination sites, so you can see and change permissions.
  • Access to the reports: on the machine that ran SPMT, or in the Migration Manager area of the SharePoint admin center.
  • Read access to the original share, which should still be intact. Do not delete or tidy anything at the source yet.
  • A short list of three to five sensitive folders (finance, HR, client files) and who should and shouldn't be able to open each.
  • Excel or similar for the CSV reports. A report with a few hundred thousand rows is a reference document, not a reading assignment.

Collect the reports before they disappear

Everything else depends on the reports, and Migration Manager's file share reports expire after 90 days. Microsoft doesn't keep the log files for you. Take copies now and store them somewhere access-controlled, because they list file names and paths and those can be sensitive in themselves.

  1. In SPMT, once the migration has finished, select Migration details. A folder opens containing the summary reports. For a single task, select View reports on that task to open its task-level reports. Copy both folders to your archive location.
  2. In Migration Manager, select the task name, then Download task report. To get one combined file for several finished tasks, tick them and select Summary report. For a large estate, Microsoft publishes a PowerShell script (aggregatereports.ps1) linked from the Migration Manager reports page that downloads task reports in bulk.
  3. In SPMT, look for FailureSummary.csv. It is only created when failures happen, so if it isn't there, no failures occurred in that task run. That is good news about failures, but it says nothing about files that were filtered out by your settings, which is what the next section deals with.

Reconcile the counts without chasing phantom gaps

Four numbers matter for each task. Scanned is everything the tool found. Filtered out is what your settings or scan problems excluded on purpose. Expected is scanned minus those exclusions. Migrated is what actually arrived. In principle, migrated plus not migrated should account for expected, and any difference between the source and scanned should be explained by filters. Anything that doesn't add up needs a name attached to it.

Filters are the usual reason a Windows file count runs higher than the migrated count. The settings that remove files quietly are: hidden files (Include hidden files in SPMT, Migrate hidden files in Migration Manager), Migrate files created after, Migrate files modified after, Don't migrate files with these extensions, and in SPMT the subsite, list and library filters. Open the settings the task used and note which were on. One file-share vendor documents the same hidden and system file effect for its own tool, which is a reminder that a raw Windows count includes files the migration tool never intended to move.

  1. Open the summary report (SummaryReport.csv in SPMT, Aggregate Summary Report.csv in Migration Manager). Check Status first, then compare the scanned, expected, migrated and not-migrated columns. The column names differ slightly between the two tools, for example Total to be migrated in current round in SPMT and Total to be migrated items in Migration Manager.
  2. For each task, open ScanSummary.csv. Note Total scanned files, Total scanned folders, Items filtered out and Items with issues. The scan runs before the migration, so these figures show what the tool intended to move.
  3. Count the files and folders in the source. This reads the share and changes nothing. Run it in PowerShell on the file server, or on any computer with read access, and replace YOUR_SOURCE_PATH with the folder the task migrated. On a large share it can take a while. Any errors it prints, such as path-too-long messages, are worth noting because awkward paths are a common cause of failed items. Compare the results with Total scanned files and Total scanned folders.
    powershell
    Get-ChildItem -LiteralPath 'YOUR_SOURCE_PATH' -Recurse -File -Force | Measure-Object
    Get-ChildItem -LiteralPath 'YOUR_SOURCE_PATH' -Recurse -Directory -Force | Measure-Object
  4. Count the hidden and system files in the same folder. A file marked both hidden and system appears in both counts. If the Windows total is higher than the scan by roughly this number, and your settings exclude hidden files, you have probably found your gap.
    powershell
    Get-ChildItem -LiteralPath 'YOUR_SOURCE_PATH' -Recurse -File -Force -Hidden | Measure-Object
    Get-ChildItem -LiteralPath 'YOUR_SOURCE_PATH' -Recurse -File -Force -System | Measure-Object
  5. Write a short reconciliation for each task: source count, scanned, filtered out, failed, migrated and the gap, if any. A gap of a handful of files should be traced by name through ItemReport.csv rather than argued over as a percentage. We wouldn't use total size as a pass or fail test, since version history and filters both affect it.

Triage the failures, then rerun

The item failure report (ItemFailureReport.csv, one per task) lists each file that didn't make it, with a Result category, a Message and an Error code. Start by grouping it, because a thousand rows are usually five or six causes repeated.

Several causes are predictable. SharePoint refuses certain names: characters such as quotation marks, asterisks, colons, angle brackets, question marks, slashes and pipes, names starting with ~$, and names such as desktop.ini. It also caps individual files at 250 GB. Take care with the SPMT setting Replace invalid filename characters. If it is Off, files with invalid characters are skipped, and a source package that generates more than 100 errors is blocked entirely, so valid files in that package are blocked as well. A short failure list can therefore hide a bigger loss, so check anything that sits beside the failed items in the same folder.

  1. Summarise the failure report. This command only reads the CSV in the folder you are in; replace YOUR_FAILURE_REPORT_FILENAME with the actual file name, which carries a round suffix such as R0.
    powershell
    Import-Csv .\YOUR_FAILURE_REPORT_FILENAME | Group-Object 'Result category', 'Message' | Sort-Object Count -Descending | Select-Object Count, Name
  2. Sort each group into one of three outcomes: expected and acceptable (Office lock files, desktop.ini), fixable at the source (rename the file, shorten the path), or needs a decision from the data owner (an oversized file, a corrupt document). Keep the file paths for each, as these become part of your sign-off record.
  3. Fix what can be fixed at the source, then run the task again as an incremental run, which moves only new or changed files. Rerunning is a normal part of SPMT and Migration Manager, but it reads the source again, so stop anyone editing the same files in SharePoint while you do it. Two live copies are how you lose someone's work.
  4. Open the new round's reports. The Incremental round or Round number increases, and the failure count for the fixed items should fall to zero. Anything that reappears goes back to the owner decision list.

Check access in both directions

Files that arrive are only half the job. Permissions are where migrations tend to go quietly wrong, and the dangerous failure is not 'someone can't open a file' (they'll tell you within the hour) but 'someone can open a file they shouldn't' (they won't).

What you should expect depends on the settings. With Preserve file share permissions Off, migrated files inherit whatever permissions the destination library has, so a restricted source folder is exactly as open as the library. With it On, Read, Write and Full control map to Read, Contribute and Full control for users the tool can match, and files with source permissions get unique permissions. The special Deny permission is not saved, so a person blocked by a Deny entry at the source can end up with access. Users the tool can't match get the default permission of the destination location. Be aware too that with the setting On and the destination set to a library root, permissions from the source root folder can replace the library's own role assignments; migrating into a subfolder avoids that.

User mapping decides which cloud identity each source account becomes. SPMT calls the setting Automatic user mapping and Migration Manager calls it Microsoft Entra lookup. Microsoft says that if you use a custom mapping file and want to preserve permissions, you should turn that setting off, so an account missing from the file isn't looked up automatically. Migration Manager's own guidance also allows leaving it on alongside a mapping file. Whichever you chose, the checks below tell you what actually happened.

The NCSC makes the point that access control is the customer's responsibility in the cloud, and that mistakes are most likely during the first move. It also cautions against over-engineered least-privilege schemes that nobody can understand. Both apply here: verify the result, and aim for a model that is simple enough to be maintained.

  1. Confirm which settings the migration used: Preserve file share permissions, the user mapping option and whether a mapping file was supplied. That tells you what result to expect for the sensitive folders on your list.
  2. Open the destination library, then Settings, then Library settings (or More library settings), then Permissions for this document library. The banner at the top tells you whether the library inherits permissions from its parent. If you see 'Some items of this list may have unique permissions which are not controlled from this page', select Show these items to list the exceptions.
  3. Check named people against sensitive folders. As a site owner or admin, open the folder's access settings, or the site's Advanced permissions settings, and use Check Permissions, entering the user's name. It shows their level and whether it comes directly or through a group. For the fictional Finance folder, check one finance team member who should have access and one sales team member who should not.
  4. Look at the membership of broad groups, for example a site Members group that includes everyone in the department, and any 'everyone' style entry on the library. A restricted folder that inherits from a broad library is open to all of them.
  5. Correct problems at folder level, using a small number of SharePoint groups rather than recreating every individual entry. Stopping inheritance on a folder starts it with a copy of the parent's current permissions, which you then edit. Microsoft supports up to 50,000 items with unique permissions in a library and recommends keeping well below that, around 5,000. Don't widen access to settle a complaint without confirming the user should have it.
  6. If mapping was wrong for many users, don't just rerun on the live library. Microsoft's documentation explains what happens on a first migration, but it doesn't spell out what a rerun does to role assignments already applied, so test a rerun against a copy of one folder first.

Spot-check content as real users

Reports tell you what the tool believes it did. A short human sample tells you whether the result is usable. Choose it by risk rather than at random: the deepest folders, the largest files, the oldest material and anything with unusual characters in its name.

  1. Take about a dozen rows from ItemReport.csv covering those categories and use the Destination column to open each file in SharePoint. Confirm it opens, looks complete and is a plausible size. If you kept version history, using the Migrate file version history setting, open the version history on a couple of files to see the versions arrived.
  2. Ask one named person from each team to sign in with their own account and open the folders they use every day. Do not rely on your admin account for this. An admin can open nearly everything, so it proves nothing about what ordinary users see.
  3. Ask them to check any documents that refer to other files by an old drive letter or share path, such as spreadsheets with external links. Those links keep pointing at the old location, which is a content issue the migration tool doesn't fix. This is engineering judgement rather than something the reports will flag.

Sign off and cut over

Cutover is the point where the SharePoint copy becomes the only copy people use. It is also the last moment when the source is still a complete fallback, so don't rush it. Keep the source intact and read-only until you have finished all of the following.

  1. Agree a freeze date and make the source read-only, using whatever method your file server supports, so nothing changes after your final run.
  2. Run a final incremental run on each task. Save its reports with the earlier ones. The failure list should match the expected and owner-decided items you recorded earlier, with nothing new on it.
  3. Repeat the Check Permissions test on your sensitive folders after the final run, in case anything moved.
  4. Point people at the new locations: update mapped drives, shortcuts and any bookmarks, and tell them where to report anything missing.
  5. Keep the read-only source, and any backup of it, for an agreed period without reports of missing files. Deleting it is the one step here you can't take back.
  6. Success looks like a short sign-off pack: the archived reports, a reconciliation note per task, the failure list with a decision against each item, and the permission checks confirmed by a named person for each team.

If it still doesn't add up

Most remaining puzzles fall into a few patterns.

  • A small, constant shortfall against the Windows count usually means hidden or system files, or a counting difference between the scan and a file-system count. Trace it with the hidden and system counts above, and then by name in ItemReport.csv.
  • Files missing but no failure report: look at Items filtered out in ScanSummary.csv, then re-read the date, extension, subsite and library filters the task used.
  • A task showing Failure with no item rows: in Migration Manager, check the Task failure reason column in the summary report.
  • Users can't see files they should: check that their source account mapped to the right Microsoft 365 identity. Unmapped users receive only the destination's default permission.
  • Users can see more than they should: the likely causes are Preserve file share permissions being Off, a Deny entry that wasn't carried across, or a broad group on the library. Fix at folder level and recheck.
  • Reports unavailable: Migration Manager file share reports expire after 90 days. If they've gone, re-run the scan-only task (Only perform scanning) to regenerate scan figures, then rebuild the reconciliation from the source and destination.
Technical terms explained
Deny
A Windows file permission entry that blocks access even when other entries would allow it. The SharePoint Migration Tool doesn't save Deny entries.
incremental run
A rerun of a migration task that looks for new or changed files in the source and moves only those, rather than copying everything again.
SPMT
The SharePoint Migration Tool, a free Microsoft Windows application that moves files from file shares and SharePoint Server into SharePoint Online and OneDrive.
unique permissions
Permissions set directly on a folder or file that no longer follow its parent, created when inheritance is stopped or when a migration brings source permissions across.
user mapping
Matching each account at the source to a Microsoft 365 account so permissions can be applied to the correct person in the destination.

Sources and further reading

KEEP THE CONVERSATION GOING

Want a second pair of eyes on a migration sign-off?

If a SharePoint migration has finished but you're not confident about the permissions or the gaps in the reports, tell us what you moved and what you have to hand.

Contact Rismor