SPMT migration errors: the codes you will actually hit and how to fix them

It is late, the cutover window is half gone, and the SharePoint Migration Tool has stopped on a line that reads:

Invalid site URL ‘http://intranet.contoso.local’ (ErrorCode: 0x0201000F)

So you paste the URL into a browser. It opens. You paste it back into SPMT. Same code.

That is the shape of almost every SPMT error. The message names a thing, and the thing it names is fine. What is broken sits one step to the side.

Microsoft does publish the codes. They just live on five different pages, sorted by which part of the product emitted them. None of those pages answer the question you have at 11pm. Is this stopping the job, or is it skipping files and carrying on without telling me?

Five causes, wearing thirty different codes

Once you group the published codes by what actually causes them, the list gets short. Nearly everything in Microsoft’s table is one of five failures.

Click to zoomTap to zoom

Work the family, not the code. If you get 0x02040012, the fix is not “look up 0x02040012”, it is “my migration machine is out of room”. The next three codes you hit will have the same answer.

The account is the first thing to check, every time

More SPMT failures come down to permissions than to anything else, and they arrive wearing four or five different codes.

0x02010017 is the honest one. It says you must be a site collection admin, and it means it. 0x02010016 says it cannot find your SharePoint Server user. 0x0201000C, 0x02010018 and 0x02030001 all resolve to some version of “check your credentials and try again”.

The fix is the same in each case, and both halves get forgotten:

1. The migration account needs site collection administrator on the source, not just the target.
2. Sign out of SPMT and sign back in after you change anything. SPMT caches the token, and a permission you granted five minutes ago is not in it.

This is also where 0x0201000F usually lands. Microsoft’s advice for that code is to check the URL is valid and open it in a browser. That is exactly the test that passes. You can open the site because you are you. SPMT is running as a different account, and that account has no rights there. Check who SPMT is signed in as before you touch the URL.

The disk that fills up is yours

Five codes point at the SPMT working folder, and the folder is on your computer, not in Microsoft 365.

0x02040012, 0x0204000A, 0x0204000D, 0x02050001 and 0x02080001 all resolve to the same folder:

%appdata%\Microsoft\MigrationToolStorage

SPMT builds a package there before it uploads anything, so a 400 GB library needs somewhere local to stage.

Microsoft’s guidance for most of these is that every file and folder in that working folder must be closed. What that means on a real machine:

• Free space on whatever drive holds %appdata%, which on a laptop is usually the same C drive that is already nearly full.
• Antivirus that is scanning the folder counts as having the files open. Exclude the path.
• Do not open the working folder in Explorer to see how it is going. That is enough to corrupt the local storage and earn 0x02050001 on the next run.

One more in this group deserves a mention, because the fix is not where you would look. 0x02010020 means the source has version history and the target library does not have versioning switched on. You either turn versioning on at the destination or turn version history off in SPMT’s settings. This is also the strongest argument for letting SPMT create the target list rather than building it by hand first: a list you made yourself is where template mismatches (0x02010010) and unsupported templates (0x02010023) come from.

There is a related message that sends people in entirely the wrong direction: “There isn’t enough disk space in the target site collection.” It reads as a tenant quota problem and it is almost always this same local folder. I covered that one, along with the published tool ceilings, in SPMT limits: file size, item count, and what actually fails.

Unique ID and IRM: the failures with no code of their own

These two failures confuse people for the same reason. Microsoft’s error table has no entry for either of them.

Information Rights Management. If IRM is switched on for a source library, the migration tool reads the files the same way a person does, which means it receives them encrypted. It then uploads the encrypted blob. The files arrive, the job may well report success, and nobody can open anything.

Microsoft’s instruction is explicit and it is a sequence, not a setting:

1. Disable IRM on the source list and on the target list.
2. Run the migration.
3. Enable IRM again on both.

IRM settings themselves are not migrated, so step 3 is yours to do by hand. Microsoft’s migration assessment scan produces an IRMEnabledLibrary-detail.csv listing every library with IRM turned on. Run the scan and work that file before your cutover, because you cannot tell by looking at a library whether it is protected.

Unique IDs. The other half of this is item identity. Every item in SharePoint carries an internal unique identifier. SPMT does not preserve the source one, so a migrated file arrives with a new identity. That is fine until something in the target already holds the spot. You get 0x01710004, and Microsoft’s own description of it is the most useful line in the error table:

Fail to look up folder name. The item may exist in other list or site in the same site collection. Or the item is in the recycle bin.

The recycle bin half catches people constantly. You deleted a test library, reran the migration, and the name is still held by the deleted copy. Empty the second-stage recycle bin on the target site collection and rerun.

Throttling, 429, and the 100,000 number that is not about throttling

If your migration is crawling rather than failing, you are being throttled.

Throttling is not negotiable. SharePoint returns HTTP 429 (“too many requests”) or 503 (“server too busy”) with a Retry-After header telling the tool how long to wait. Microsoft is blunt about the rest:

Throttling is in place to protect the reliability and availability of the service. Throttling rules can’t be disabled or suspended. Opening a support ticket doesn’t lift throttle.

Retried requests still count against your limits, so hammering the retry button makes the throttle last longer. The per-user ceiling is 3,000 requests per 5 minute window. Microsoft throttles background work like migration harder during weekday daytime hours and eases off evenings and weekends, which is the real reason cutovers happen on Saturdays.

Now a correction, because the internet has this one wrong. You will see 100,000 quoted in throttling advice, as though a list crossing 100,000 items starts triggering 429s. It does not. The 100,000 threshold is a permissions limit. Above that item count you cannot break permission inheritance on a list, library or folder, and you cannot reinherit it either. Individual items inside it can still carry unique permissions.

That matters for a migration, just not the way the throttling posts suggest. If your plan involves migrating a 150,000 item library and then breaking inheritance on it to set up access, the plan does not work and no error code will tell you why until you try. Split the library first.

The limits that do shape a migration, all from Microsoft’s own pages:

Long paths are skipped, and nothing tells you

This is the failure that costs people the most, because it does not look like a failure.

SharePoint allows 400 characters for the entire decoded path including the file name. Meet a file over that and SPMT does nothing clever. It will not shorten the name or flatten the folders, and it does not retry. It writes one line in the failure report, moves to the next file, and the task finishes.

Click to zoomTap to zoom

Everything in that right column behaves the same way. A file checked out at the source (0x0131000F) is skipped. A folder ending in _files is skipped, because SharePoint treats it as a thicket folder and refuses to create it. Blocked characters produce 0x0201000E and that item is skipped.

So the validation step after a migration is not optional, and it is not “does the site look right”. It is a count. Compare item counts per library, source against target, and read the failure report line by line. A task that says it succeeded has told you nothing about whether everything arrived.

Fix long paths at the source, and shorten the folder names rather than the file names. Nobody can find a file you renamed, and one shortened folder near the top fixes hundreds of items at once.

When SPMT will not install at all

A smaller problem, but it wastes an afternoon when it hits. Microsoft lists the requirements and most of them are things nobody checks:

• The machine must be x64.
• .NET Framework 4.6.2 or higher.
• Microsoft Visual C++ 2015 Redistributable for x64. SPMT bundles most of what it needs and misses some system DLLs, so installing the redistributable separately resolves dependencies the installer cannot.
• Stop third party antivirus before you install.

If you get “Application SharePoint Migration Tool is already installed from another location”, that is a half-finished previous install. Uninstall, then reinstall. The current released build at the time of writing is 4.1.130.4, and if a documented fix is not behaving, checking your version is a faster test than most of the alternatives.

What this does not fix

Reading codes correctly does not make the tool do things it cannot do.

SPMT migrates from on premises sources. It is not a tenant to tenant tool, and no error code will tell you that politely. If you are moving between tenants you are in a different product category.

It will not rebuild anything custom. InfoPath forms, 2013 workflows, full trust code and custom web parts appear in the scan as risks, not as items with fixes. Those are rebuild line items and they belong in a separate budget.

And the throughput ceilings are SharePoint’s, not the tool’s. Every migration product uses the same Migration API and gets throttled the same way. Paying for a commercial tool buys you better reporting and better handling of failures. It does not buy you a faster ceiling.

And if you hit a code with no cause listed here, escalate it rather than guessing. Pull the correlation ID out of the failure report first. Support asks for it immediately, and it never appears in the on screen message.

The bottom line

Stop looking up the code and ask which of the five families it belongs to. Check the account first and your own disk second. Then treat any task that “succeeded” as unverified until you have compared item counts and read the failure report.

The expensive failures are the quiet ones. A skipped file writes a line in a report nobody opens, the task goes green, and you sign off on a migration that is missing content. That bill arrives weeks later.