The Drupal 9 upgrade Config Split issue and how to fix it

By Inviqa
Content management | Technology engineering

‎

Our upgrade to Drupal 9 went swimmingly – or so we thought – till we noticed a glitch: the Drupal Config Split module didn’t work!

Thankfully for us, this just meant a gap in our Google Analytics data. But for other brands and organisations, this ‘little glitch’ could have a much more devastating impact, like: 

  • your website not showing the correct live content,
  • your website having development modules enabled that harm the user experience, 
  • or even your website not allowing payments.

With Drupal 8 coming to the end of its life in November 2021 we embarked on upgrading our own Inviqa sites to Drupal 9. We’re big fans of learning fast and early, so this was the perfect opportunity to gain some valuable learnings before upgrading our clients’ sites to Drupal 9. 

Oops – Drupal 9 broke our Google Analytics.

Drupal 9 broke our Google Analytics, but thankfully it was just that – and now we know why and how to fix it! Here’s how. 

How we’re using Drupal Config Split on the Inviqa websites 

Let’s start with understanding what the different modules do and how we use them on our Inviqa sites.

Drupal has a feature called Configuration Management, which is responsible for managing a collection of admin settings that determine how your site functions.

The Drupal Config Split module is a brilliant addition to Configuration Management, which allows you to separate out configurations depending on different situations or different environments. Drupal Config Split also has a dependency on a few other modules, like Config Ignore and Config Filter. These are all modules that don’t come with Drupal Core, but need to be enabled manually – and therefore upgraded manually as well. 

On the Inviqa websites, we use Drupal Config Split to separate out different settings for Google Tag Manager (GTM): 

  • Non-production / local sites: GTM is completely disabled on local environments.
  • Staging sites: are using the same GTM container as on live, but a staging GTM environment, which allows us to test our GTM settings and any changes before pushing them to the live environment.
  • Production / live sites: our main live GTM container is enabled permanently.

We know from having worked on many client sites which are built on Drupal, that Config Split is often used in considerably more complex ways, which would also help in highlighting any issues earlier on. 

Deploying the Drupal 9 upgrade to production 

After deploying the Drupal 9 upgrade to production, we noticed that our Google Analytics wasn’t recording traffic. 

The live / production environments were practically seen as ‘local’, so Config Split hadn’t enabled Google Tag Manager (GTM) at all on the live site and none of the tags, including Google Analytics (GA), were firing. This meant that we lost GA tracking for a short while and we saw a small gap in the data. As soon as this was detected, we manually enabled the configuration on production and GTM and GA were back up and running again instantly. 

We quickly identified that the issue was related to the Drupal Config Split module and that there was a problem with how the different settings were applied to the various environments. 

In a nutshell: the config didn’t split and the live site had the config settings for the local sites, which clearly wasn’t right.

Finding a permanent fix for the Drupal Config Split issue

With the Config Split, Config Ignore, and Config Filter modules all heavily dependent on one another, we started investigating if any known patches were available for these modules. 

While investigating, we found that the Drupal community had already reported a similar issue around Config Split not working in Drupal 9, and when digging deeper, we found the real patch to our problem: 

Updating config_split --with-dependencies results in Composer updating config_filter to the latest 1.x version. At the point of our Drupal 9 upgrade and writing this article (July 2021), the latest version was 1.7 and the fix was included in version 1.6, which was available since 19th of August 2020. 

Pull request for Drupal 9 upgrade Config Split issue fix

Summary and key takeaways 

To summarise, when we upgraded to Drupal 9, we missed to update the dependencies in the Config Split module, which upgrading config_split --with-dependencies does. That coupled with a lack of hard version requirement in config_split for config_filter to require a version of 1.6 or higher, meant that the Drupal Config Split module was simply not working at all with our setup. 

The key takeaway from this experience is that if you are looking at upgrading Drupal 8 to 9, then be sure to check over the version of your Config Filter module, as you’ll need version 1.6 or higher, and to update config_split --with-dependencies. Also, be sure to test your Config settings thoroughly on all your environments. 

And if you need any further help, then do give us a shout!