Troubleshooting a Joomla Update problem
- Published in Joomla Help
Troubleshooting Joomla Update Errors
Troubleshooting a Joomla Update problem
A few things can go wrong when updating Joomla though later releases tend to have fewer and fewer issues. We describe some common issues and provide solutions here as well as examining tools to diagnose the root causes.
1. One-click didn't work. The one-click update basically grabs the update files from the Joomla code repository and installs them similar to the way extensions get installed. If you're behind a firewall or on a weak connection this can fail. In this case, you have the option of downloading the upgrade package ZIP file manually and installing it via the Joomla update extension. If that fails there is a third option where you extract the contents of the upgrade package and overwrite the files on your Joomla installation. If you use that method you'll also need to follow our next troubleshooting tip to apply the database update.
2. Database check. Oftentimes part of a Joomla update includes database changes. The one-click update, or package upload methods should look after these. If a database error shows up after an update, navigate to Extensions > Manage > Database to see if the database matches the new version. There is a 'Fix' button which will correct the issue if it does not match.
3. Whitescreen (of death) Despite the fright you may get if you see nothing appear after an update, this simply means that something is stopping any output from being generated, or there is nothing to output. To help you diagnose the problem, it's useful to turn on, or increase the level of the built-in error reporting. To turn on error reporting navigate to System > Global Configuration and click on the Server tab. the setting for Error Reporting is probably st 'System Default'. Switch that to Maximum or Development and refresh the website frontend to see what information it generates. In the System tab there is also a setting for Debug System which will add debug information to the bottom of all pages. It can be helpful especially for database query issues. Remember to switch these back after you're done.
4. Third party Component, Module or Plugin errors. Sometimes you miss an extension when doing your pre-checks and find out afterwards that an extension is breaking the site. If the administrator area is still running you can deactivate the extension to check if it causes the problem. Then you can update it in the normal way. To disable an extension, navigate to Extensions > Manage > Manage and unpublish it on this list. Remember to reactivate it once you've updated the extension.
5. Inaccessible administrator area. If you can't access the administrator area, you can turn on error reporting or deactivate extensions in other ways. To turn on error reporting you need to edit a line in the configuration.php file which is located in the root directory of your web hosting. On or around line #23 change
public $error_reporting = 'default'; to public $error_reporting = 'development';.
To unpublish an extension that you suspect is causing the error, you need to access the database, navigate to the #__extensions table and change the 'Enabled' field from 1 to 0 for the extension you want to deactivate. If these are a little advanced for you, ask your web developer or get in touch with us to help.
6. Check the logs. You may have access to logs via a file in the root directory called error_log which is a simple text file you can open with notepad or other text editors. It shows the exact date and time of all errors and is really helpful for finding problems. If you don't see that file, you can ask your hosting company to check for any recent issues record in their log files.
7. Check Google and the Joomla forum. Search Google an Joomla websites with the error messages you see or with keywords about the problem you're experiencing. You can also ask for help on the forums, and to get the best replies make sure you include the specific versions you're using and what exact steps you took before the error occurred.
8. Is it a migration? If you are on an older core version of Joomla, you will be looking at a migration rather than an update. Joomla 4 is the current major version, so if your version number begins with a 3, 2 or 1 then you are on an older version and will need Joomla 3 to Joomla 4 Upgrade Help. Migrations can be a little trickier, so feel free to ask for assistance!
Having problems? Get a free Joomla assessment from us