The restore precheck: every point explained

Before a restore writes anything, the plugin checks nine points. Here you learn what every point checks, what its finding means and what you can do in case of a warning or a block.

The pre-check is in the tile Prepare restore on the Restore page. You open the tile with Restore latest backup or in the menu of a backup with Restore.

When the pre-check runs

• By itself on opening: the pre-check starts as soon as the tile Prepare restore opens.
• After every change: if you change the scope, a switch or the view, the pre-check runs once more shortly afterwards. The result of the most recent pre-check always counts.
• By hand: Run pre-check repeats the pre-check.
• In the restore itself: the first step of every restore is the same pre-check. If a point blocks there, the restore ends before anything is written.

The pre-check writes nothing to the website. For two points the plugin creates folders, a file and tables as a probe and removes them again immediately.

1. The note stands in place of the switches until the first pre-check has answered: the pre-check determines the defaults of the switches. Only the Extended view shows it.
2. Run pre-check shows a waiting symbol as long as the pre-check is running.
3. As long as there is no result yet, every point shows a spinning ring and checking …
4. Start restore is blocked until the pre-check has passed.

Reading the result

1. The line names the duration of the pre-check and the target from which the backup is read. The target is named by its ID, for example “local-1”.
2. Every point of the pre-check has a coloured dot, its name, the state and the finding.
3. Not restored: names what the restore leaves out, and why.
4. Start restore is free: no point blocks the start.

Every point ends with one of four states. After the state stands the finding in words.

State	Meaning	Start possible
green OK	The point is in order.	yes
yellow Warning	Something you should know. You judge the risk and decide.	yes
red Blocked	The restore cannot start like this.	no
grey Not checked	The point could not be determined.	yes

The nine points

1. Backup readable and complete

The plugin reads the backup at a target where it is stored completely. A local folder takes precedence. Checked is: every file of the backup is at the target, the info file is valid, and every part has the size that is given in the info file. That is the short check. Every block of the backup is read by Check backup on the Backup page: Check a backup.

Finding	Meaning	What you can do
OK read in place at a local target	The backup is in a local folder. The restore reads it there.	Nothing.
OK read through the work folder	The backup is at a remote target. The restore fetches it part by part into the work folder of the plugin.	Nothing.
Blocked files missing at the target: …	The named files of the backup are no longer at the target.	Restore another backup. If the same backup is still stored at a second target, the command line reads it from there with --target.
Blocked files with a different size at the target: …	The named files do not have the size that the backup records.	As in the row before. Check backup reads the backup in full and marks it in the list. If it fails at this target, the next pre-check reads from another target where it is stored completely.
Blocked no complete copy at any target	The list of backups knows no files of the backup at this target.	Restore another backup.
Blocked the info file is missing or unreadable	The info file describes what is in the backup. Without it the backup cannot be read.	Restore another backup.
Blocked an English code instead of a sentence	The target did not answer, or the info file could not be fetched or read. For these cases the page has no sentence of its own.	Test the target on the Targets page: More …, then Test connection. Then run the pre-check again.

If the backup cannot be read, points 2 to 8 remain unchecked. They then read Not checked. For the finding the page has no sentence of its own at these points: an English code stands there. Below the points the note about a different website, which point 7 describes, is then shown as well.

1. The point Backup readable and complete has a red dot and blocks the start: files of the backup are missing at the target.
2. Points 2 to 8 have a grey dot and are not checked because the backup could not be read. The digit stands at the middle one of them. The last point, Self-request possible, the plugin checks independently of this.
3. The pre-check blocks the start.
4. Start restore is blocked.

2. PHP and MySQL version

The plugin compares this website with the values with which the backup was made: PHP, kind and version of the database server, character set of the database, version of WordPress, table prefix and Multisite. A backup from an older version of the plugin also counts as a difference. For PHP and the database server the first two digits of the version count: 8.3 and 8.4 are different, 8.4.1 and 8.4.5 are not. The point never blocks.

Finding	Meaning	What you can do
OK same versions as the backup	Nothing differs.	Nothing.
Warning … difference(s), listed below	Below the points stands the list of differences, one per line.	Read the list and check the risk yourself, for example whether your plugins and your theme run with the PHP version of this website.

3. Free space

The restore builds the files next to the live folders. For this, every root, for example the plugins or the uploads, needs as much space as its files in the backup take, plus a small extra per file. This is how the plugin calculates:

• Folders on the same disk count together.
• A reserve always stays free: 256 MiB or 2 % of the disk, whichever is more.
• The work folder of the plugin needs space for two parts of the backup. If the database belongs to the scope, the size of its data is added.
• The free space of the database server the plugin cannot measure.

Finding	Meaning	What you can do
OK enough space everywhere	The space is sufficient at every location.	Nothing.
Not checked free space could not be measured everywhere	The server does not name the free space for every location. The start stays possible.	Check the free space with your hosting provider before you start.
Blocked not enough space to build the uploads next to the live folder	For everything else the space is sufficient, for the uploads it is not. Below the points the block No way back appears.	Free up space, or choose the way without rollback explicitly: Restore uploads when there is not enough space.
Warning the uploads will be replaced in place (no way back)	You have ticked the way without rollback. The start is free.	Remove the tick again if you do not want this way.
Blocked not enough space for the code roots	At at least one location the space is not sufficient, even if the uploads do not count. That may also be the work folder of the plugin.	Free up space on the disk, or choose a smaller scope in the Extended view. The space per location is named by the pre-check on the command line.
Blocked a root folder is unknown	The scope includes a root whose folder the plugin cannot determine on this website.	Take this root out of the scope in the Extended view. The page does not name it: remove the ticks one by one until the point no longer blocks.

This is what the pre-check looks like when the server does not name the free space:

1. The point Free space has a grey dot. After it stand the name, the state Not checked and the finding free space could not be measured everywhere.
2. Start restore is free: a point that is not checked does not block the start.

4. Write permissions at the target folders

This means the folders of the website into which the restore writes, not the targets of the backups. In every chosen root folder the plugin creates its build folder as a probe and removes it again. For this the WordPress root folder must be writable, even if the core does not belong to the scope: during the switch-over, the file for the maintenance mode lies there. If a root folder is missing on this website, for example the folder of the must-use plugins, the restore creates it. For this the folder above it must be writable.

Finding	Meaning	What you can do
OK writable	The plugin may write into every folder.	Nothing.
Blocked a root folder is not writable	In at least one root folder the plugin could not create its folder, or a missing root folder cannot be created.	Give the web server write permissions on this folder. Which one it is, the pre-check names on the command line.
Blocked the WordPress root folder is not writable	In the root folder of the installation the plugin could not create a file.	Give the web server write permissions on the WordPress root folder.
Blocked the plugin has no folder code yet	The folders of the plugin carry a code in their name. This code the plugin could not create or not save.	Get help: Get help: support report, troubleshooting and diagnostics.

5. max_allowed_packet vs. largest row

max_allowed_packet is a setting of the database server: this is how large a statement may be at most. The backup records its largest row. This row must fit into the limit with a reserve of 4096 bytes.

Finding	Meaning	What you can do
OK the largest row fits into max_allowed_packet	Every row of the backup can be inserted.	Nothing.
Blocked a row is larger than max_allowed_packet	The database server of this website would not accept the largest row of the backup. Such a row the plugin cannot restore.	The value is changed by whoever manages the database server, usually your hosting provider. Without the database, the rest can be restored: in the Extended view remove the tick at Database.
Not checked could not be read from the database server	The database server did not name the value. The start stays possible.	Run the pre-check again.
Blocked the database server could not be reached	The pre-check could not connect to the database. The same finding then also stands at points 6 and 8.	Run the pre-check again.

6. Collations

A collation defines how the database compares and sorts text. The plugin compares the character sets and collations of all tables and columns of the backup with those that the database server of this website knows. utf8 and utf8mb3 count as the same. The point blocks only if the database server cannot be reached.

Finding	Meaning	What you can do
OK all character sets and collations are known here	Nothing has to be replaced.	Nothing.
Warning … replaced, listed below	The database server does not know everything the backup uses. Below the points stands what the import replaces with what.	Check the risk yourself. A replaced collation can change sorting and searching. If it considers two values equal that were different before, the import stops at a duplicate key before anything is switched.
Not checked not recorded in this backup (older plugin version); the import checks them	The backup comes from an older version of the plugin and does not carry the list yet.	Nothing. The import checks when it creates the tables.
Not checked could not be read from the database server	The database server did not name its collations.	Run the pre-check again.
Blocked the database server could not be reached	See point 5.	Run the pre-check again.

This is how the plugin chooses the replacement: a collation that distinguishes upper and lower case or compares binary becomes the binary collation of its character set. Every other one becomes the default collation of its character set on this server. If the character set itself is missing, the character set of the connection applies.

7. Same website

A backup carries a fingerprint made of the address of the website and its path on the server. The plugin compares it with this installation. The point never blocks, but it changes the defaults of the switches.

Finding	Meaning	What you can do
OK this website	The backup comes from this installation. By default the WordPress core, the drop-ins and the files .htaccess, web.config and .user.ini are also part of the restore.	Nothing.
Warning a different website	The backup comes from another website or from another path. By default the WordPress core, the drop-ins and the files .htaccess, web.config and .user.ini are left out.	What you want to restore anyway, you switch on in the Extended view: Restore a backup on another website.
Warning unknown origin (no fingerprint); treated as a different website	The backup carries no fingerprint. The defaults of a different website apply. It is never rejected.	As in the row before.

With both warnings, below the points stands Different website: this backup was made on another site. The site address stays the one of this website.

8. Database rights (probe)

The plugin does not read a list of rights. On throwaway tables it does what the restore will do: create, insert, create an index, a second table with a foreign key, a trigger, a view, rename, drop. Afterwards it removes everything again, even after an error.

Finding	Meaning	What you can do
OK create, insert, index, rename, drop, foreign key, trigger and view work	The user of the database may do everything the restore needs.	Nothing.
Warning foreign key, trigger or view refused; the import leaves them out	Tables and data can be restored. Foreign keys, triggers or views the import does not create and says so in the result.	Check whether your website needs these objects. The rights are granted by whoever manages the database, usually your hosting provider.
Blocked create, insert, index, rename or drop refused	The user of the database lacks a right without which the restore does not work.	Ask your hosting provider for the right. At which step the probe failed, the pre-check names on the command line, with the message of the database server.
Blocked the database server could not be reached	See point 5.	Run the pre-check again.

9. Self-request possible

After the switch-over the new website has to confirm itself. This point says by which way that happens: via the self-request, with which the server calls its own address, or via the open page in the browser. The point never blocks.

Finding	Meaning	What you can do
OK the self-request works; the new website confirms itself	The server reaches itself.	Nothing.
Warning no self-request: keep this page open until the restore is confirmed	Self-requests do not arrive on this server. The open Restore page confirms the new website in its place.	Keep the page open until the restore is finished. Without confirmation the plugin switches everything back after 60 seconds.
Not checked not tested yet	No self-request has run on this website yet. The start stays possible.	Keep the page open. Whether self-requests arrive is determined by Check task sources on the Settings page, in the Extended view in the tile Scheduler.

When the database does not belong to the scope

If you remove the tick at Database in the Extended view, points 5, 6 and 8 do not apply. All three then read OK without anything having been checked. For the finding the page has no sentence of its own: an English code stands there saying that the database is not chosen. The list of differences then lacks table prefix, plugin version and the details about the database server.

1. Database is not ticked: the database is not restored.
2. The point max_allowed_packet vs. largest row is green without a check: the database is not chosen.
3. The same applies to the point Collations.
4. The same applies to the point Database rights (probe).

What stands below the points

1. A point with a warning has a yellow dot; state and finding stand in yellow.
2. The list names the differences between the backup and this website, one per line.
3. Replaced on import (unknown to this database server): names per line a collation of the backup and its replacement.
4. Not restored: names what the restore leaves out, and why.
5. The note says that the backup comes from a different website and the address of this website stays.
6. Start restore stays free: warnings do not block the start.

Differences

Above the list stands Differences between the backup and this website. You judge the risk; the restore goes the best possible way: Every line has the form …: backup …, here …

Line	What is compared
PHP	The PHP version, first two digits.
WordPress	The version of WordPress.
Table prefix	The prefix of the tables. The import converts the tables of the backup to the prefix of this website.
Multisite	The line appears if the backup or this website is a Multisite. Multisite is not supported: the backup contains only the tables of the main website. The values are given in English: yes or no.
Plugin version	The backup comes from an older version of the plugin. In it, columns whose default is an expression may be missing; the import names them, and they get their default value.
Database	The kind of database server: MySQL or MariaDB.
Database version	The version of the database server, first two digits.
Database character set	The character set of the database server.

If the database server does not know a character set or a collation of the backup, that is in the list as well. These lines begin with the English word charset or collation.

Replaced on import

The list appears if the import has to replace a collation. The point Collations then warns. Every line names on the left the collation of the backup and on the right, after the arrow, the replacement that the import takes. The list names at most 50 entries.

Not restored

The line names every root and every file that the restore leaves out, with the reason in brackets.

Reason	Meaning
never restored	Applies to this plugin with its folders and tables and to the file wp-config.php. The file is in the backup but is never written back. In the line it is named as “wp-config”.
not in the backup	The chosen root is not contained in this backup.
WordPress core not chosen	The switch Do not restore WordPress core is ticked.
left out by your choice	You have deselected the drop-ins or the files .htaccess, web.config and .user.ini.
left out on a different website by default	The backup comes from a different website. Drop-ins and the files .htaccess, web.config and .user.ini are left out as long as you do not switch them on.

When a point blocks

1. The point that blocks has a red dot; state and finding stand in red.
2. The pre-check blocks the start.
3. Start restore is blocked.

Fix the cause and click Run pre-check. Once no point blocks any more, Start restore is free.

No rollback: the uploads do not fit next to the live folder

1. The point Free space blocks the start.
2. No way back is the title of the block, with a warning triangle in front of it. Below it stands what is irreversible.
3. Replace uploads in place anyway (cannot be undone) is the choice of this way. The checkbox is empty by default.
4. The pre-check blocks the start.
5. Start restore is blocked as long as the choice is not ticked.

When the pre-check does not complete

1. The note stands in place of the switches: the defaults are not determined yet. Only the Extended view shows it.
2. Run pre-check starts the pre-check again.
3. The message of the server names the cause, in red.
4. not checked yet stands at every point.

Message	What you can do
This backup is complete at no target.	The backup is no longer stored completely at any configured target, for example because the target was removed. Restore another backup.
This backup does not exist.	The list no longer knows the backup. Reload the page and choose a backup from the list.
another message	Click Run pre-check.

See also

• The “Restore” page
• Restore the website from a backup
• Restore only parts
• Restore a backup on another website
• Restore and import with WP-CLI

On the command line

WP-CLI not set up yet? How to install WP-CLI.

The pre-check also runs with WP-CLI and writes nothing to the website while doing so. The output is in English: one line per point with state and finding, then what is not restored, then the differences. The output names details that the page does not show: the root folder without write permission, the space per location, the table with the largest row and the step at which the probe of the database rights failed. If a point blocks, the command ends with an error.

# Show the backups with their job names
wp cloneworx-backup backup list

# Run the pre-check for a backup
wp cloneworx-backup restore precheck <Job>

# Read the backup from a specific target
wp cloneworx-backup restore precheck <Job> --target=local-1

# Check only database and uploads
wp cloneworx-backup restore precheck <Job> --roots=db,wp-uploads

# Include what another website leaves out by default
wp cloneworx-backup restore precheck <Job> --include-core --include-dropins --include-htaccess

# Choose the path without rollback for the uploads
wp cloneworx-backup restore precheck <Job> --uploads-in-place