J4.x

Difference between revisions of "Joomla Update Problems"

From Joomla! Documentation

m (Added section on hosting - FPA reports often show php.ini values too low.)
 
Line 37: Line 37:
  
 
The following troubleshooting instructions are organised by update step to make it easier to find the information you are looking for. Furthermore, it is an exhaustive resource, based on more than a decade of experience troubleshooting all possible (and some borderline impossible) problems with Joomla and extension updates. It lists problems which are extremely unlikely to occur. Don't let its length scare you; you are very unlikely to ever see any of these problems occur.
 
The following troubleshooting instructions are organised by update step to make it easier to find the information you are looking for. Furthermore, it is an exhaustive resource, based on more than a decade of experience troubleshooting all possible (and some borderline impossible) problems with Joomla and extension updates. It lists problems which are extremely unlikely to occur. Don't let its length scare you; you are very unlikely to ever see any of these problems occur.
 +
 +
== Hosting ==
 +
 +
Many problems are caused by some default php.ini values set by hosting services. You can either change these yourself or ask your hosting service to change them for you. Make sure these settings are equal to or more than the following:
 +
* memory_limit: 256M
 +
* upload_max_filesize: 32M
 +
* post_max_size: 32M
 +
* max_execution_time: 30
  
 
== Determining if updates exist ==
 
== Determining if updates exist ==

Latest revision as of 14:11, 27 May 2023

Joomla Update[edit]

Joomla Update is the core component responsible for determining whether a newer version of Joomla is available for your site. You can access it from the Administrator menu System  Update  Joomla or Home Dashboard  Notifications  Joomla icon, even if the site is up to data.

If your site is not up to date you will see a screen similar to the following:

J4x-joomla-update-problems-pre-update-check-screen-en.png

The three sections may have Tick or Warning symbols, for the illustration above:

  • Required Settings are satisfied.
  • Recommended Settings has a problem (Display Errors is set to On in Global Configuration for testing).
  • Extensions has a problem (one of the extensions does not report compatibility data).

If you think the problems will not interfere with a Joomla update you may choose to go ahead and update.

If your site is up to data you will see a screen similar to the following:

J4x-joomla-update-problems-uptodate-screen-en.png

If you select the Check for Updates button you will see the following sceen:

J4x-joomla-update-problems-reinstall-screen-en.png

This screen allows you to reinstall the Joomla core files.

If you go ahead and update from any of the above screens there are many different ways in which the update may fail.

  • It may start downloading an update file but appear to stall - a green progress bar does not go to completion.
  • It may appear to complete but throw a fatal error when Joomla tries to return to an Administrator screen.
  • It may display the following screen:
J4x-joomla-update-problems-error-screen-en.png

Troubleshooting[edit]

The update process consists of several different steps. While every care has been taken to make this process as trouble–free as possible there's always a small chance that something may go wrong, typically due to a very restrictive server configuration or network conditions on a very small minority of sites.

The following troubleshooting instructions are organised by update step to make it easier to find the information you are looking for. Furthermore, it is an exhaustive resource, based on more than a decade of experience troubleshooting all possible (and some borderline impossible) problems with Joomla and extension updates. It lists problems which are extremely unlikely to occur. Don't let its length scare you; you are very unlikely to ever see any of these problems occur.

Hosting[edit]

Many problems are caused by some default php.ini values set by hosting services. You can either change these yourself or ask your hosting service to change them for you. Make sure these settings are equal to or more than the following:

  • memory_limit: 256M
  • upload_max_filesize: 32M
  • post_max_size: 32M
  • max_execution_time: 30

Determining if updates exist[edit]

Joomla will make a request to its update server over HTTPS and download an XML file provided by the Joomla project listing the latest available versions. The update server in use can be determined by going to System, Update, Joomla, clicking on Options and examining which update server is in use. You are recommended to use the Default update server to receive updates to your current major version of Joomla. Use Joomla Next when you want to upgrade your site to the next major version of Joomla — this is best done on a copy of your site to avoid any nasty surprises; not all third party extensions and templates will be compatible across major Joomla versions. The major version of Joomla is the first digit in the Joomla version, before the first dot. For example, the major version of Joomla 4.0.1 is 4.

If Joomla cannot determine that an update is available please check the following:

  • The Joomla Update information may be out of date in the database. Go to System, Update, Joomla and click on Check for Updates. You should see an update screen as illustrated above.
  • The update sites information in Joomla may be corrupt. Go to System, Update, Update Sites and click on Rebuild. You should see a green System Message saying Update sites have been rebuilt from manifest files. Then go to System, Update, Joomla and click on Options. Select the Testing update channel. Click on Save & Close. Click on Options again. Select the Default or Joomla Next update channel — depending on your preference — and click on Save & Close. The Save action ensures that the settings are correctly updated.
  • Your host may prevent making outbound HTTPS requests at all or restricts them to predefined allowed IP addresses. Please ask them to allow outbound HTTP requests to https://update.joomla.org This is a CDN, meaning that the exact IP address will be different depending on where the world you are trying to access this URL from. Do tell your host; they will know what to do with this information.
  • Your host may have an outdated SSL library which does not understand the modern TLS certificates used by the Joomla update CDN. Please ask your host about it.

Determining if third party software is compatible with the new version you are about to install[edit]

Joomla does not have a magical way of evaluating third party code for compatibility. Its report is based solely on the extension information kept in Joomla's #__extensions table, the update sites provided by the installed extensions and the update information provided by the developers of third party extensions including but not limited to which version of their software is compatible with which version of Joomla.

If the information displayed is incorrect please check the following:

  • What is the minimum stability for extension updates? Go to System, Update, Extensions and click on Options. The ‘Minimum Extension Stability’ determines which is the minimum stability level of a third party software that Joomla will take into account when evaluating compatibility. For example, if this option is set to Stable but only a beta version of a third party extension is compatible with the Joomla version you want to upgrade to Joomla will tell you that there is no compatible version of the third party extension available.
  • The update information may be out of date. Go to System, Update, Extensions and click on Check For Updates. Then go back to System, Update, Joomla and see if the extension now appears as compatible or if you are told than a compatible update to it is available.
  • The update sites information in Joomla is corrupt. Go to System, Update, Update Sites and click on Rebuild. Then go to System, Update, Joomla and click on Options. Select the Testing update channel. Click on Save & Close. Click on Options again. Select the Default or Joomla Next update channel — depending on your preference — and click on Save & Close.
  • Your host prevents making outbound HTTP/HTTPS requests at all or restricts them to predefined allowed IP addresses. This will prevent Joomla from retrieving update information from third party update sites. First go to System, Update, Update Sites. Below each update site you will see its URL. Make a list of those URLs. Then ask your host to allow your site to make requests to these URLs. Please note that some of these URLs may point to a CDN, meaning that the exact IP address will be different depending on where the world you are trying to access this URL from. Do tell your host; they will know what to do with this information.
  • Your host may have an outdated SSL library which does not understand the modern TLS certificates used by most third party extension developers' update sites. Please ask your host about it.
  • You may have “orphaned” extensions. Most modern Joomla extensions are delivered as ‘package’ type extensions which include two or more related extensions. When installing a package extension Joomla records a package extension in its database. It then records the package ID to each of the installed extensions from that package in the database. The update information is provided for the package, not each individual extension. This association may break if you used Discover to install the extensions, extracted the package and installed the separate extensions directly, Joomla failed to record the package ID for each extension when installing the package (most likely because an error occurred) or your site has been upgraded from an old version of Joomla which predates the use of packages in extensions. In this case even updating the extension will NOT update the package association. There is currently no solution to this except determining manually the compatibility of extensions with each Joomla version.
  • In some cases the number of requests Joomla sends to your server as it determines compatibility for each extension may overwhelm the server and trigger a Denial of Service protection. In this case some or all of the extensions will appear as of indeterminate compatibility status. Unfortuantely, you will have to check the compatibility of each extension manually against the information published by extension's developer.

Downloading the update[edit]

Joomla will need to download its update package, a ZIP file which is very similar to the Joomla installation ZIP file but without the web installer (the `installation` directory). This could fail for a few reasons:

  • The ZIP file is rather big. Joomla 4 update packages are around 25MiB. If your server is slow, overwhelmed or has poor connectivity with GitHub — where Joomla update packages are downloaded from — it may take a long time to download the package. If that time is longer than your server's PHP maximum execution time, its maximum CPU usage limit (as determined by ulimit -t in the server command line), the PHP-FPM timeout or the web server's timeout the download will fail and you will see an error page. You will have to ask your host for help with that.
  • You may not have enough free space on your site. You need enough space to store the compressed update ZIP file and its extracted files. As a rule of thumb, you need about 50–60 MiB of free space for Joomla Update to work correctly. Do note that the free space reported by your hosting control panel is not always realtime, i.e. it may ‘lag’ several minutes or hours behind the actual disk space usage on your site. Moreover, further limits may be imposed by your host. If unsure, please ask your host.
  • Your host prevents making outbound HTTPS requests at all or restricts them to predefined allowed IP addresses. Please ask them to allow outbound HTTP requests to `https://github.com`. This is a CDN, meaning that the exact IP address will be different depending on where the world you are trying to access this URL from. Do tell your host; they will know what to do with this information.
  • Your host may have an outdated SSL library which does not understand the modern TLS certificates used by GitHub. Please ask your host about it.

Extracting the update[edit]

After the update ZIP file has downloaded Joomla needs to extract it on your site. Since Joomla is effectively replacing itself and because this process does take some time to complete it cannot happen within Joomla itself. Instead, a separate file (administrator/components/com_joomlaupdate/extract.php) is used to perform the update. This file is inert except when an update is in progress.

You may get an error during the extraction for one of the following reasons:

  • You cannot access the extract.php file because of a server protection e.g. a customised .htaccess file on Apache and Litespeed servers. Try accessing https://www.example.com/administrator/components/com_joomlaupdate/extract.php from a web browser, where https://www.example.com/ is to be replaced with the URL to your site. You should see the message {"status":false,"message":"Invalid login"} If you see anything else you are being forbidden from accessing this file.
  • If you can access the file but extracting the update fails immediately there is a different server protection on your site which prevents the request to `extract.php` from being handled by that file. Please contact your host about this.
  • If you are using CloudFlare go to Rules and create a new Page Rule. Set the If URL Matches to */administrator/components/com_joomlaupdate/extract.php and Then The Settings Are to “Disable Security” and on a new line ”Cache Level”, ‘Bypass’. Set the Order to First. Click on Save and Deploy. This ensures that CloudFlare will not try to block the update extraction.
  • The update ZIP file is corrupt or truncated. This could happen if downloading the update file failed with an error. Go back and retry. See also the previous section.
  • If you are using upload and update i.e. you uploaded the update ZIP file yourself please make sure that you are using only the official Joomla Update ZIP files. The extraction script only supports a subset of the ZIP archive format used by the official update ZIP files.
  • Did you run out of disk space? Please check the section above.
  • Is the ownership and permissions of all files correct? Joomla needs write access to all of its files and folders. If unsure, ask your host. There is no specific set of “good” permissions! The permissions needed depend on the ownership of your files and which system user the web server runs under.
  • Did you lose network connectivity or your network has very high latency? It's possible that the request fails because of that.
  • The extraction takes place by making consecutive requests to the aforementioned extract.php file. Each request is set up to take between 3 and 4 seconds. The process repeats until the entirety of the update file has been extracted. On some servers this cadence of requests to the same file from the same IP address may trigger the server's security. On other servers it may trigger a different server protection, e.g. a maximum PHP time limit, a maximum CPU usage limit or another server timeout. On even fewer servers running on CloudLinux it could trigger a server memory outage situation if your server was already running low on memory. You need to contact your server about that; there is nothing you can do yourself to work around these server limitations.

Finalising the update[edit]

This is a two step process.

Right after the update ZIP file has been extracted a final step will run which removes old files. When upgrading to a new major version of Joomla the list of files to remove is pretty big and the process may timeout. Moreover, the point made in the previous section about ownership and permissions of files is important here too; Joomla needs write permissions to the old files and folders it has to remove. If this step fails you can resume it from the command line. Go into the cli folder and run php joomla.php update:joomla:remove-old-files If you cannot do it yourself ask your host to do it for you. You will also need to follow the workaround for the next step.

Finally, Joomla reloads and you are logged back into the administrator interface. At this point Joomla updates its database tables and performs any database administration tasks. If this fails you can resume the process by going to System, Maintenance, Database. Select Joomla CMS from the list and click on Update Structure.