How-to
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 five 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.
- Tries a page again when the new site's database was too busy to save a page or other code file. It waits, checks that the earlier try did not land, and tries again. If the database is still too busy, it says so plainly and tells you a final sync copies the file. The file is not listed as refused.
- 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.
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 instance. 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 instance's CLI tab in Insites Console. For the old site, see Get the key for each instance.
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 instance 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.
Some actions take longer than the page waits. When that happens and the action probably worked, the page tells you to reload and not press the action again, and it tells Insites which action was slow. The tool's first responder reads that report with the run, so a slow page is not read as a failure.
While the tool reads the old site’s pages, files, stylesheets, sitemap, robots.txt and redirects (and a GitHub repository), a break in the network is waited out by itself: a request that gets no answer at all is asked again for up to about a minute, with growing pauses. If the network stays down, the migration stops with “A network outage stopped the tool reaching the old site”. That is not a fault in the site. Press Carry on, or Run again. An answer from the site, such as 404 or 401, is never asked again.
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, or its Insites name, 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.
If the button is missing. Run again is offered on the latest run of a migration that has loaded. When a later run of the migration has loaded, the older run shows a short line in its place, with a link to the later run: open it to run again with the latest fixes. A nightly sync that is waiting at its plan, or that stopped or failed before it loaded, does not count as a later run.
When the new site is live. After the domain step on Cutover is done, Run again is no longer the main action. The card says: “The new site is live. Run again would plan over changes made on the new site since the load, so use it only if you are sure.” Run again anyway is still there, behind a confirm where you type a word. If the migration is finished, use Launch, then Close.
When the old site is gone. If the old site cannot be found or read, for example because it was deleted, Run again is not offered. The card says: “The old site cannot be found or read, so Run again has nothing to read and is not offered. The new site is not affected.” The tool says the same if you press Run again while the old site is not there.
File columns. If an earlier load stopped and left old text in a file column, Run again clears that text, saved first so Roll back restores it, and copies each file into its row. The plan names the column under Worth knowing.
Forms saved before October 23. Settings saved before then could call a form by its short name, such as recover_password, and the new site showed “Could not find Form”. Every run, the nightly sync and Run again included, now writes the full name, such as modules/website/recover_password. Nothing you chose changes.
If a plan is waiting from before a release. A plan that waits for its code while a newer release ships was built without that release's fixes. Confirm the load then says which version built the plan and which is running now, above the plan code. For a plan made by Run again, it links to the migration it came from: press Run again with the latest fixes there. For any other plan, press build the plan again: it keeps every decision and builds the plan on the version running now, from the copy of the old site already read. To also pick up fixes in how the old site is read, use Plan it again from the same source: it starts a new migration that reads the old site again, and you give both keys and make your decisions again. You can still confirm the plan as it is.
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.