Troubleshooting Guide
Update Troubleshoot Guide¶
Error Message |
Explanation |
Resolution |
|---|---|---|
Unable to connect to WSO2 Update |
The Update Tool is not able to connect to the WSO2 Update Server due to a network failure or the server response is not successful. |
Check your network connection. If the connection is still failing, please report to WSO2 at https://wso2.com/contact Please be sure to attach the details of the error when you report it. You can get the details by getting the log files in `updates/logs` in the product directory. |
File validation failed |
Local modifications have been made to the file being updated. |
If the update command is being executed, delete the content in the <UpdatesHome>/updates (~/.wso2-updates/updates) directory and run the update tool again. If the hotfix command is being executed, download the hotfix file again and run the update tool against the newly-downloaded file. If the connection is still failing, please report to WSO2 at https://wso2.com/contact Please be sure to attach the details of the error when you report it. You can get the details by getting the log files in updates/logs in the product directory. |
| Error while downloading update file from UpdateFileURL | The Update Tool is unable to download an update file from the WSO2 Update service due to a server error. | Try running the update tool again. If the command continues to fail, please report to WSO2 at https://wso2 .com/contact. Please be sure to attach the details of the error when you report it. You can get the details by getting the log files in updates/logs in the product directory. |
| Unable to get MD5 hash of file | The update tool is unable to find the md5sum value of the file. | Try running the update tool again. If the command continues to fail, please report to WSO2 at https://wso2 .com/contact. Please be sure to attach the details of the error when you report it. You can get the details by getting the log files in updates/logs in the product directory. |
| Update configurations are not loaded | Update tool has encountered an error while loading the configuration values from the config file. | Try running the update tool again. If the command continues to fail, please report to WSO2 at https://wso2 .com/contact. Please be sure to attach the details of the error when you report it. You can get the details by getting the log files in updates/logs in the product directory. |
| Error while initializing updates config file | Update tool encountered an error while being executed for the first time. | Try running the update tool again. If the command continues to fail, please report to WSO2 at https://wso2 .com/contact. Please be sure to attach the details of the error when you report it. You can get the details by getting the log files in updates/logs in the product directory. |
| Invalid credentials | The credentials provided are not valid. If the WSO2 account was created recently, the reason for the login failure may be that the credentials are not synced with the WSO2 Update Server. | Try again by providing the correct credentials. If your account was created a short while back, you might have to wait. If authentication is still failing, please report to WSO2 at https://wso2.com/contact. Please be sure to attach the details of the error when you report it. You can get the details by getting the log files in updates/logs in the product directory. |
| Username or password cannot be empty | The update tool is executed without providing values to the username or password. | Provide your credentials for the Username and Password and try again. |
| Unable to parse JSON file | Error while reading JSON file while running the update tool when updating or applying hotfix. | Unable to parse config.json: Check the JSON file at <ProductHome>/updates/config.json and fix issues with formatting. Unable to parse update.json: Remove the content in the <UpdatesHome>/updates (~/.wso2-updates/updates) directory and run the update tool again . Unable to parse hotfix.json: Download the hotfix file and apply the hotfix to the newly-downloaded file. If the error still persists, please report the issue to https://wso2.com/contact. Please be sure to attach the details of the error when you report it. You can get the details by getting the log files in updates/logs in the product directory. |
| Unable to identify the product | The update tool cannot identify the product it will be updating if the product.txt file is absent
or if the information in the product.txtis been altered. |
Make sure that the <ProductHome>/updates/product.txt file exists and the file contains valid product information. |
| Only one service can be enabled at a given time | The configuration has enabled multiple services. | Check the <ProductHome>/updates/config.json file |
| Unable to revert as backups could not be found | The backup that was taken previously is no longer available in the location the backup was taken to. | Check for the backup directory from the config file at <ProductHome>/updates/config.json and check if any modifications were made to that environment. |
| Cannot revert because the backup directory has been modified. | The state of the backup is different from when it was taken. | Check for the backup directory from the config file at <ProductHome>/updates/config.json and check if the content of the backup is valid. If so, manually copy the directory to the current product setup. |
| Invalid update level | The current update level contains an invalid value. | Check if the configuration file in <ProductHome>/updates/config.json has been modified manually to contain an invalid value such as a non-numeric value for the update level. |
| Invalid requested update level | The update level provided along with the --level flag is invalid. | Check if a valid product version or non-numeric characters are provided for the update level.
eg:
* level 3.1.0.4 * level 4 |
| Insufficient disk space | The machine does not have sufficient space to update the product. | Clear some disk space in the machine and run the update tool again. For more information on the issue please refer the Best Practices page |
| Error while extracting downloaded clients | An error occurred while the update tool is updating itself. | Check if the update tool has permissions to execute files in the <UpdatesHome>/updates (~/.wso2-updates/updates by default) directory and run the update tool again. If the error still persists, please report the issue to https://wso2.com/contact. Please be sure to attach the details of the error when you report it. You can get the details by getting the log files in updates/logs in the product directory. |
| Invalid hotfix name | The hotfix being applied contains an invalid name. | Download the hotfix again and run the apply-hotfix command. If the error still persists, please report the issue to https://wso2.com/contact. Please be sure to attach the details of the error when you report it. You can get the details by getting the log files in updates/logs in the product directory. |
| Backup directory <backup_directory> cannot be inside the product directory <product_directory>. | Backup and the product pack location cannot be same. | Change the backup location to a new location that is not within the product pack. For more details on changing the backup location refer how to change the backup location |
Permission Restrictions¶
You may encounter the following error messages due to permission restrictions at an OS level.
Error Message |
Explanation |
|
|---|---|---|
| Unable to create directory | The update tool is unable to create the specified directory in the relevant location. | |
| Unable to open file | The update tool is unable to open a file in the relevant location. | |
| Unable to read file | The update tool is unable to read a file in the relevant location. | |
| Unable to read directory | The update tool is unable to read the content of the directory in the relevant location. | |
| Unable to write to file | The update tool is unable to write to a file in the relevant location. | |
| Unable to create file | The update tool is unable to create a file in the relevant location. | |
| Unable to close file | The update tool is unable to close the file at a relevant location. | |
| Unable to delete file | The update tool is unable to delete the file at a relevant location. | |
| Unable to move file | The update tool is unable to move the relevant file to a specified location. | |
| Unable to delete the file | The update tool is unable to delete a file in the specified location. | |
| Error while writing updates configurations to file | An error occurred while the update tool is modifying its configurations. | |
| Unable to get the size of the directory | An error occurred while attempting to get the size of a directory. | |
| Error while writing updates configurations to file | An error occurred while modifying the configurations of the update tool. | |
| Error while deleting product directory | An error has occurred while attempting to delete a product directory. This occurs during a revert process. |
If you encounter any of the above listed OS related issue:
- Check the OS-level permissions for creating directories in the relevant locations.
Infor
You can enable permission to create directories in the <UpdatesHome> directory (~/.wso2-updates by default).
-
Check the available disc space and free some space if the available space is insufficient.
-
If the error occurs even after enabling the above permissions, please report to WSO2 by accessing the Contact page. Please be sure to attach the details of the error when you report it. You can get the details by getting the log files in
updates/logsin the product directory.