NickSchick | Freelance Design Concepts - IT Specialists
 

Upgrading and Updating GRAV | Troubleshooting Edition

Hits: 3580
| How-To, Trouble Shooting | GRAV CMS

Do you have a GRAV installation needed the update to 1.7? At the time of the creation of this article, the Stable GRAV release is version 1.17.15. Most instances of GRAV tend to upgrade without issue, but we are going to address the rare case you find yourself facing an error. We have seen our fair share of errors while upgrading and updating and would like to drill down some of the troubleshooting procedures and fixes we apply.

Check Requirements First

Let's get requirements out of the way as they can cause problems with the performance of your GRAV instance.

Your server should support:

  • Web Server (Apache, Nginx, LiteSpeed, Lightly, IIS, etc.)
  • PHP 7.3.6 or higher

NOTE:
Apache minimum requirements are to have the modules mod_rewrite and mod_ssl installed and enabled.

PHP Module Requirements are:

  • curl (client for URL handling used by GPM)
  • ctype (used by symfony/yaml/Inline)
  • dom (used by GRAV/admin newsfeed)
  • gd (a graphics library used to manipulate images)
  • json (used by Symfony/Composer/GPM)
  • mbstring (multibyte string support)
  • openssl (secure sockets library used by GPM)
  • session (used by toolbox)
  • simplexml (used by GRAV/admin newsfeed)
  • xml (XML support)
  • zip extension support (used by GPM)

Upgrade/Update Methods

There are three ways to upgrade GRAV Core. They do vary in procedure but are all effective.

  • The Admin Panel or Admin Plugin
  • CLI (Command Line Interface)
  • Manually upgrading the Files with the latest release

Upgrade through Admin Panel

The average user will most likely be using the admin plugin. This plugin allows for control over GRAV using a graphical user interface (or GUI). This interface has many features including, the ability to upgrade your GRAV CORE version.

GRAV-admin-update

The most straightforward way you can upgrade GRAV is via a prompt located in your admin system dashboard. This prompt also notifies you when you have outdated or updatable plugins.


An upgrade is available but not visible on the dashboard

If your upgrade prompt is not showing via your dashboard, you might need to enable the Automatically check for updates feature for the prompt to display.


Via Admin Plugin (Admin Dashboard)

To accomplish this, access the configuration section of the admin plugin and navigate to:
Admin Panel -> Plugins -> Admin Panel -> Automatically check for updates and set to Enable

Automatic-check-for-updates


Via CLI or FTP

Alternativaly you can edit the admin.yaml file to accomplish the same goal.
Edit this file: {GRAV_Directory}l/user/plugins/admin/admin.yaml

admin-plugin-file

Find the entry enable_auto_updates_check and confirm the setting is true. If there is no entry listed in this file, you may add it at the bottom: enable_auto_updates_check: true


Proceed to update the system via the prompt and follow the upgrade/update instructions within the panel to complete the upgrade process.


NOTE:
To upgrade plugins, you will most likely need to upgrade your core version of GRAV. Release cycles for plugins are often released with core updates to accommodate the core code changes in the GRAV version release.


Upgrade through CLI

More advanced users will opt to upgrade or update via CLI. The built-in CLI is a powerful tool that comes with GRAV and can simplify all most every process, including upgrading and updating. The errors that can come from the browser-based admin plugin should not happen. We typically do not find any issues with the upgrade process when using CLI, and this is we recommend this method to upgrade GRAV or any of its components. 

[user@hostname public_html]$ php bin/gpm self-upgrade

GPM Releases Configuration: Stable

Grav v1.7.15 is now available [release date: Wed May 19 19:23:01 2021].
You are currently using v1.6.19.
Would you like to read the changelog before proceeding? [y|N] n
Would you like to upgrade now? [y|N]


How to use GRAV CLI

To learn more about the GRAV CLI, visit our article Grav PHP CLI Tutorial. This article is our "beginners guide" on how to get started with the built-in GRAV CLI.


Manually Updating Your Root Directory

Manually updating or upgrading GRAV Core, although very effective, is time-intensive. This process includes retrieving a fresh copy of GRAV Core and Manually implementing your data into it, and reloading the root directory manually. We do not recommend this procedure as it is complicated and time-consuming. In rare situations, we have used it.


github-grav-release


Some Common Upgrade Issues

So now you have upgraded GRAV, and you see an error. Please keep in mind, while issues are rare when upgrading or updating, the below-mentioned issues seem to be the most common.

PHP Version Conflicts

Recently we have found an issue resulting in this error message: An exception has been thrown during the rendering of a template ("Trying to access array offset on value of type null"). This issue seems to stem from PHP7.4. The quick fix is to downgrade to version 7.3 or update to PHP8. We have had success with both workarounds and have Production Sites Running in both environments successfully.

Something else to look out for in the current release of GRAV is, you are required to run PHP7.3 or higher. When you upgrade via the admin plugin, the system will show you an error if your server environment is not compatible. The funny part is if you upgrade via CLI, you will not receive a single warning. The update will run without actually updating. Again, this might be a bug in this plugin release. Future versions might resolve this issue.

Whoops there was an error!

One of the most common error screens you will find when working with GRAV. Output is a “Critial Error” and will log the information on why it has happened. There are additional debugging features, but typically this screen will be enough to understand what the error is. Below you can see an example of such a page.

server-error

These errors are useful in identifying the actual problem. There is a log for which might contain additional information for troubleshooting located in {GRAV_ROOT}. You can all find this information in the admin section of your web application (if you have access to this). These errors can be triggered and displayed in both the Front-end Web Application (or FWA) or the Admin Plugin.

Examples of some errors you might encounter:

  • Erroneous data format for unserializing 'Grav\Common\Flex\Types\Users\UserObject'
  • Template "partials/noscript.html.twig" is not defined in "partials/base-root.html.twig" at line 55.
  • CSS Style Sheets not rendering, making your website and/or dashboard display incorrectly.


Steps to Correct

Clear Browser Cache
The first thing to try would be to your browser cache, especially if you are running some form of advanced cache system or a service worker (PWA).

Clear Grav Cache
If the error is still there it is time to fire up the CLI and clear the cache in the system. Run the command “bin/grav cache”. This command will automatically clear cached information and hopefully resolve your issue.


Advanced trouble shooting

90% of your cases will be resolved by simply following these steps. In the rare case that this method does not resolve your issue, it is recommended to disable plugins one by one until you have located this plugin causing the error.

When you fine the plugin that is causing the issue you can simply leave it disabled (if not in use) or troubleshoot the plugin.

Additionally when custom plugins are used they must confirm the latest requirements of the GRAV Core version. As an example all of our clients have had great success with the Grav system, but all of our clients use custom-developed Grav systems to accomplish different goals.

Hopefully, this information has saved you some time.

Leave a Comment