This article describes what is done during the upgrade process in CS-Cart and Multi-Vendor. It covers the problems that may arise at different stages of the upgrade, and what might cause those problems.
Warning
This article is intended for experienced users with system administration skills. If you can’t solve the problem by yourself, please contact CS-Cart’s technical support.
Here are the actions that are performed during the upgrade of CS-Cart or Multi-Vendor:
So-called validators check specific bottlenecks related to the upgrade process. For example:
Validators are described as step 0 because different checks are performed during different steps of the upgrade.
The upgrade package is downloaded and unpacked.
The backup of files and database of the site is created.
The link for restoring the pre-upgrade site from backup is sent to the administrator’s email.
Note
Administrators can choose to skip backup creation in two cases:
Migrations make changes to the database.
The files are copied from the upgrade package; the files that don’t exist in the newer version of CS-Cart/Multi-Vendor are removed.
The languages from the updated PO files are installed.
The cache is cleared.
The information about the upgrade is saved to the database.
The permissions on PHP scrips in the root directory of the installation (admin.php, api.php, index.php) are set the way they were before the upgrades.
After this the upgrade is complete.
Important
The information about many of problems described below is saved to the upgrade log. It is a core_log.txt file that will be created in the var/upgrade directory of the CS-Cart/Multi-Vendor installation when an upgrade is attempted.
Validator errors usually occur before the actual upgrade begins; there is an exception, but it occurs after the upgrade is performed. That’s why there’s no need to restore the site from backup in case of validator errors—solving the problem is enough.
Error message:
Validator "Restore" returned fail status
The restore validator checks whether or not the pre-upgrade version of the site can be restored from backup. If this error occurs, here are the possible causes:
Wrong permissions on files and directories.
The web server doesn’t allow to run the restore-from-backup script. This script is created with the same permissions as specified in DEFAULT_FILE_PERMISSIONS in the config.local.php file.
One of the ways to solve this problem is to change the permissions in the file to those that will allow to run the script. The necessary permissions depend on the settings of your server.
cURL-related problems:
cURL isn’t installed on the server.
сURL returns an empty response body.
The responses to cURL requests return errors.
Loopback connection is prohibited on the server, which leads to the following error:
HTTP error: curl (56): Failure when receiving data from the peer
The upgrades directory or the source_restore.php file in that directory is missing. If the file or directory is missing, you can take them from the installation archive of your current version of CS-Cart or Multi-Vendor.
To get the archive with the necessary version, contact the technical support via Help Desk and say which version of CS-Cart or Multi-Vendor you need. The support specialists will upload the archive to your File Area.
The upgrade is performed on a test copy of the installation on a different server with the same domain name; the hosts file on the client’s computer has an entry with the IP address of the test copy.
In this case the copy tries to connect to the live store. There are 2 ways to solve the problem:
Error message:
Package contains migrations that were not described in schema or schema has links to missing migration files
The error may mean that:
The upgrade log has an error like this:
There was a problem creating the schema table: Invalid default value for 'end_time'
The problem occurs in older versions when NO_ZERO_DATE mode is enabled in MySQL. The problem was solved starting with 4.4.х.
Error message:
Upgrade is impossible due to file integrity check error. Please contact the technical support team
When a file integrity check error occurs, it’s best to contact CS-Cart’s technical support.
Error message:
Validator "Backup" returned fail status
The error means that the backup wasn’t created. The problem could be caused by the lack of hard drive space.
If the upgrade package can’t be downloaded, then more often than not you’ll find the reason in the upgrade log. Here are some of the possible reasons:
URL-file access (the allow_url_fopen directive) is disabled on your server, so the file_get_contents function doesn’t work. This reason isn’t logged.
There isn’t enough free hard drive space. This reason isn’t logged.
The URL of the Upgrade Center is wrong or is missing in the config.php file. It should be this:
$config['updates_server'] = 'http://updates.cs-cart.com';
The proxy settings that prevent the download of the upgrade are specified on the Settings → General page.
The permissions on the var/upgrades directory to which the upgrade files are supposed to be downloaded are wrong.
If the upgrade package can’t be unpacked, here are the possible reasons:
If the backup of the site isn’t created, this could be caused by the following reasons:
The timeouts are too low on the server. The problem could be caused by the limited execution time for PHP scripts (we recommend setting max_execution time to at least 3600) or by FastCGI and MySQL settings.
Hint
To find out whether the upgrade is still going on, check the browser tab. If the loading animation is displayed on the tab, it means that the upgrade is still working.
There are files with non-latin symbols in their names (most often those are style names) — in that case you’ll see a detailed error message. To solve the problem, rename the files appropriately and run the upgrade again.
To rename a style, open it in the Theme Editor, duplicate the style and specify an appropriate name. After that select the duplicate style and delete the original style.
The database has non-standard tables (for example, from third-party add-ons) with forbidden symbols in table names — in this case there won’t be an error message. The problem is solved by renaming the tables in accordance with MySQL requirements: use only latin characters, numbers, underscore, and the $ symbol in the names.
The Validator "Backup" returned fail status error; it most likely means that there isn’t enough free hard drive space. This reason isn’t logged.
The upgrade won’t start if it isn’t possible to send an email with the restore-from-backup link to the administrator’s email address. Most of the possible reasons are described in a separate article. The problem can also occur if the site administrator’s email address isn’t specified on the Settings → Company page. Either way, the upgrade log will contain a record about the error.
These problems can be caused by non-standard structure of the database or by an error in a migration. As a result, the occurring SQL errors will appear in the upgrade log.
If you experience problems with migrations, we recommend restoring the store from pre-upgrade backup and contacting CS-Cart’s technical support.
Problems at this stage can occur if the timeouts are too low on the server. The problem could be caused by the limited execution time for PHP scripts (we recommend setting max_execution time to at least 3600) or by FastCGI and MySQL settings.
Hint
To find out whether the upgrade is still going on, check the browser tab. If the loading animation is displayed on the tab, it means that the upgrade is still working.
If the upgrade stops at this step, we recommend restoring the site from the pre-upgrade backup.
Problems at this stage can occur if the timeouts are too low on the server. The problem could be caused by the limited execution time for PHP scripts (we recommend setting max_execution time to at least 3600) or by FastCGI and MySQL settings.
Hint
To find out whether the upgrade is still going on, check the browser tab. If the loading animation is displayed on the tab, it means that the upgrade is still working.
If the upgrade stops at this step, we recommend restoring the site from the pre-upgrade backup.
Problems at this stage can occur if the timeouts are too low on the server. The problem could be caused by the limited execution time for PHP scripts (we recommend setting max_execution time to at least 3600) or by FastCGI and MySQL settings.
Hint
To find out whether the upgrade is still going on, check the browser tab. If the loading animation is displayed on the tab, it means that the upgrade is still working.
At this stage the upgrade itself has already been completed. If necessary, you can clear the cache manually.
When the information about the upgrade is saved to the database, problems can occur due to the following reasons:
The timeouts are too low on the server. The problem could be caused by the limited execution time for PHP scripts (we recommend setting max_execution time to at least 3600) or by FastCGI and MySQL settings.
Hint
To find out whether the upgrade is still going on, check the browser tab. If the loading animation is displayed on the tab, it means that the upgrade is still working.
There is no information about the upgrade package. The upgrade is completed properly, but the following message appears:
Validator "0" returned fail status
An SQL error is recorded to the upgrade log:
Caught an exception: Tygh\Exceptions\DatabaseException: Column 'type' cannot be null <b>(1048)</b><p>INSERT INTO cscart_installed_upgrades (`type`, `name`, `timestamp`, `description`, `conflicts`) VALUES (NULL, NULL, 1504536222, NULL, 'a:0:{}')</p> in /path/to/store/app/Tygh/Database/Connection.php:1118
In this case go to Administration → Upgrade center, click the gear button, and choose Refresh available upgrades. Otherwise the upgrade that you already installed may appear on the list of available upgrades.
Sometimes during the upgrade the chmod can’t be executed. That command is used to set the permissions on PHP scripts in the root directory of a CS-Cart and Multi-Vendor installation as they were before the upgrade.
The problem usually manifests as an entry in the upgrade log: other than that, the upgrade is completed, and the store works properly. However, if you experience a problem right after the upgrade, it’s a good idea to check the ownership and permissions of the following files: admin.php (it should have a different name), api.php, and index.php.
During the upgrade the store is always closed. This is done to let you check if everything is alright in the store before your customers see it. Here’s what you should do:
After that you can open your store for customers.
Questions & Feedback
Have any questions that weren't answered here? Need help with solving a problem in your online store? Want to report a bug in our software? Find out how to contact us.