Console · Migration Tool
When something goes wrong
Last updated 18 November 2026
When something goes wrong
When a migration stops on a problem, or stops making progress, the migration page and the email say three things: what happened, who acts, and what to do. The main button opens the screen where you do it. This page lists each kind of problem.
Who acts is one of three:
- You do this. Something only you can change, such as a key. The button opens the screen for it.
- Insites fixes this. The problem is on our side. Insites has been told already. You can try carrying on. If it fails again, we will be in touch.
- Nothing to do yet. The tool is waiting, or keeps trying by itself. The message says when to act.
Nothing a migration has done is lost when it stops. Carry on starts again from where it stopped, and keeps everything it already did. During a load, Carry on after a failure checks every database again, so anything you fixed on the new site yourself is seen. If you no longer need a migration that failed or was stopped, an owner can delete it: it leaves your list, and nothing on either site changes.
When the tool reads the problem for you
When a migration fails, pauses to try again, or a check fails, the tool reads what happened before it shows you anything. It looks at the error, the step, how far the migration got, the run log, and the release the plan was made on. It then says, in place of the usual message:
- What happened, in plain words.
- Whether anything is lost. Usually nothing is.
- The one right action. When trying again cannot work, the page does not offer Carry on.
Under the message, How we know lists the evidence. Each line says Measured (it is in the migration’s own record) or Inferred (a conclusion drawn from it), so a wrong reading is easy to spot. When the tool did something by itself, Done by itself says what.
The tool reads each problem as one of five kinds: a problem in the tool, something in the old site’s data, something on the new site (for example a field of the wrong type, or a table left from an earlier move), a short outage or limit, or not known yet. Insites is told about every problem except a first short outage, and a problem in the tool is also logged for the team to fix.
The tool does only four things by itself, and each is logged on the migration under Activity:
- Plans the migration again when its plan was made before a release that fixed its error. Planning writes nothing to either site, and you still approve the new plan before anything loads. You get an email saying so, and the new plan is waiting for you on the Plan step.
- Sends smaller batches when the same call to the new site timed out twice at the same place.
- Waits longer when a site asks the tool to slow down, at least 10 minutes when it has asked more than once.
- Stops trying again when every try would meet the same failure, rather than using up all six tries.
Anything that would change the new site’s fields or data, such as recreating a field as an Upload field, is only suggested. You make that change. If the reading service is not available, you see the usual message described below.
Details for support. Under each problem on the migration page, and at the end of the email, is a short line for support. It names the migration and the kind of problem. If you email [email protected], include it. It never holds a key or any of your data.
The key for the old or new site no longer works
What it means. The site turned down the key the tool was given for it. A key stops working when a newer one is made, when it expires, or when it is for a different site. A Console access token for the new site is replaced each time someone presses Get my token, and lasts 90 days.
You do this. Press Replace the key. Paste a new key: the tool tests it first, then uses it in place of the old one. Then press Carry on. For the new site, get the token on the site's CLI tab in Insites Console. For the old site, see Get the key for each site.
The key is missing a permission
What it means. The site accepted the key, but the person or account it belongs to is not allowed to do everything a migration needs. On the new site, a migration changes code and settings, which needs the Developer role.
You do this. Ask an admin of the site in Insites Console to give you the Developer role. Get a new token, press Replace the key, then Carry on.
The old or new site did not answer
What it means. The tool asked the site for something and got no answer, after several tries. This is usually short: the site is busy, restarting, or briefly down. Sometimes a firewall or a security plugin answers in its place, or the address no longer works.
Nothing to do yet, in most cases. Wait a few minutes, check the site opens in your browser, then press Carry on. If the message says something in front of the site blocked the tool, let the tool through the firewall or security plugin first. If the site moved, plan the migration again with its new address.
While the load copies files, the tool waits by itself when the new site, or the storage that holds its files, stops answering. It asks again now and then for up to 20 minutes, then carries on from where it was and skips the files already there. Activity says how long it waited. A file the storage refused, rather than did not answer, is a failed file: ASSETS names it, and Copy again on Verify copies it.
The new site refused a change
What it means. The tool asked the new site to save something, and the new site said no.
Insites fixes this. Insites has been told. You can try Carry on. If it fails again, we will be in touch.
A limit was reached
What it means. A site has a limit on how fast it can be asked for things, or on how large one answer can be, and the tool reached it.
Nothing to do yet. Wait a few minutes, then press Carry on. The tool picks up where it stopped, and reads in smaller pieces when it can.
The migration reached its AI limit
What it means. Each migration can use AI up to a limit set for your account. Once it is reached, the AI stops: collection pages and new databases get the plain defaults for you to check, page photographs are compared without the AI’s reading, and Ask about this migration stops answering. Everything else in the migration carries on.
You do this. To raise the limit for your account, email the Insites support team at [email protected]. Include the migration ID and your account’s name. The message on the migration has a link that fills these in. Once the limit is raised, the same migration uses the AI again.
The new site changed since the plan
What it means. Something on the new site is not as it was when the plan was made, so loading now could write over it. Or the tool's copy of the old site has expired.
You do this. Press Plan it again and type the old site's address, which the dialog shows, to confirm. The tool reads both sites again and builds a new plan. Nothing is written until you approve it.
A problem on the Insites side
What it means. The tool hit a problem of its own, or Insites could not finish setting up part of the new site, such as a table. It is not something you did. Nothing after that part was loaded.
Insites fixes this. Insites has been told. You can try Carry on. If it fails again, we will be in touch. If the part is a table and you would rather not wait, leave the table behind on Transform, Databases, with a reason, then carry on.
A check failed
What it means. The load finished, and the checks found differences between the old site and the new site. Each check is named.
You do this. Press See what failed. Each failed check says what differs and how to fix it. Fix it or accept it, then check again. Do not move the domain until they pass. See the checks.
If a code file differs because your team changed it on the new site on purpose, press Keep the new site's version rather than copying it again. It stops counting as a problem, and no final sync writes over it. See Keep the new site's version.
A check says Not checked
What it means. The check could not read what it compares, so it could not say whether anything differs. The old site gave no answer, refused the tool, or sent every page to its other address, or the new site could not be read. It is not a failure and not a pass, and it does not count against the migration. The check says what could not be read and why.
Nothing to do yet, in most cases. Check the old site opens in your browser, then press Check again on the check, under Worth a look. It runs the checks again without loading anything. If bot protection on the old site turns the tool away, the tool reads those pages through its browser instead. If the browser is turned away too, the reason says who did. When it is the old Insites hosting, that is on the Insites side: carry on, there is nobody to ask. Otherwise ask the site's owner to allow requests carrying the X-Insites-Migration-Tool: 1 header and then check again, or carry on. See an old site that refuses the tool.
No progress
What it means. The tool is working, and has not got any further for 30 minutes. It keeps trying to carry on by itself, and most stalls clear on their own. You get one email, and Insites is told as well.
Nothing to do yet. Open the migration. If its progress still has not moved:
- Press Stop it. The step ends at a safe point, and everything done so far is kept.
- Press Carry on. It starts again from where it stopped.
After a fix: run again with the latest fixes
What it means. A release fixed something your migration met. You do not need a new migration to get the fix.
You do this. On Verify, in the result, or on the Launch timeline, press Run again with the latest fixes. The new run starts faster than it used to, because the checks made before it starts now run at the same time. A key the site refuses is still caught before the run starts, and the page says so. The old site is read again and the plan comes first. Rows already copied are brought up to date where they are, never copied twice, and rows changed on the new site since the load are kept as they are there. The nightly sync stops while it runs.
The page could not reach the tool
What it means. Your browser asked the Migration Tool for something, such as reading the migration or saving a change, and got no answer, or an error from the tool's server. A message at the top right of the screen says which, and what the page was doing:
- Your device looks offline. Your browser says it has no network connection.
- Couldn't reach the Migration Tool server. Your device is online, but the request did not arrive. The server may be restarting, or the connection dropped for a moment.
- The Migration Tool server had a problem. The server answered with an error of its own, such as HTTP 502. This is on the Insites side.
- Did not answer within 60 seconds. The page stopped waiting. A change may still have been saved, so the page reads the migration again before you press anything. Some buttons do not stop at 60 seconds, because the work they start can take longer: Run again with the latest fixes, Copy it again, Copy this one again, Check this file again, Copy the old site's version again, Accept, with a reason, the actions on Verify, and Check for changes and the launch checks on Launch. Each keeps reading the migration until what you asked for is there, then shows the result or opens the new run. A refusal from the tool still shows at once.
Your migration keeps running on the server whatever the page can reach: nothing is lost because a page could not connect.
You do this. Check your connection, then press Retry on the message. It sends the same request again and, when it works, the message goes and the page shows what is true now. While a migration is working, the page also keeps trying by itself, and the message goes once it can read the migration. Press Report a problem on the message if it keeps happening: the report includes the message. Close it with the X in its corner. On a phone the message sits at the bottom of the screen instead.