Remember that great website everyone at your company loved (or at least tolerated) that you were forced to migrate to a newer system? And the team you trusted to do so maybe bit off more than they can chew? What may have been once a perfectly nice looking and functional website, now becomes a mess of bizarre issues, poor performance, or sometimes, an almost unusable site.

If this sounds familiar and you are running into strange issues after you upgraded your Drupal 7 (or 6) site to Drupal 9 (or 8), please read this article till the end. We are going to get into the common problems site owners face after they upgrade Drupal 7 (or 6) to Drupal 9 (or 8) and how they can be solved. This won’t cover all issues we see when we come in for a migration rescue, but should at least get you to a point where you can go to sleep at night.

Drupal 7 to 9 Upgrade - The Fundamental Challenge

The first question you’re probably asking yourself is, “Why?” Upgrading from Drupal 7 to Drupal 9 (Drupal 8 has now been sunsetted) seems like it shouldn’t be that hard from a platform perspective. 

Well, Drupal 8 changed everything. It had a complete architectural overhaul so the CMS could be more sustainable, relevant and easier to get a hang of in the long term. It’s adoption of modern technologies and frameworks like object oriented programming, Symfony, Twig, latest PHP versions and (so much) more, have also allowed the Drupal community to grow exponentially by accommodating a wider range of skills to help build Drupal. Which means, it is now easier to find an expert to build and maintain your Drupal website. The great news is that upgrading to any future versions of Drupal (like Drupal 8 to Drupal 9) after that initial migration is extremely easy and won’t require a rebuild. 

But back to the problem at hand, many organizations are still migrating from Drupal 7 to 9 which does involve a complete rebuild of the website. The rebuild itself is complex enough without maintaining the current content structure that it can give the most seasoned developers fits. And in most cases, larger websites need even more attention as they tend to have multiple contributed and custom modules that don’t have a straight upgrade path. All that together opens infinite opportunities for errors.

For teams that haven’t attempted this type of migration, more often than not, the first Drupal 7 to 9 migration mistake is lack of preparation. The first and the most significant step for a successful Drupal migration is to have a thorough migration audit done to analyze every little detail of the current website structure. Not only does this report help you assess the implications of the migration but will also give you insights on areas of improvement. The next most important step is to decide whether to allow a specialized Drupal development partner (someone who breathes Drupal day in and day out) to do the migration. Just like you would prefer a heart surgeon to perform a bypass surgery over an orthopedic surgeon; having a specialized Drupal-focused company to build your Drupal website will lead to a successful migration. 

Common Drupal 7 to 9 Migration Challenges

One of the most common sources of frustration after a Drupal 6/7 to 8/9 migration is not knowing where to begin when dealing with problems. How do you, with or without coding skills, find out where the real issues lie? Easy - check your error logs. I know, it sounds like you’re opening up another can of worms trying to understand what the logs say, but we’ll walk you through the common ones below.

Let’s dive straight into some of the most common issues faced by Drupal site owners after a Drupal 7 to Drupal 9 migration.

Website is barely up / broken

1. Server issues: Your server can be compromised if you do not have enough permissions to access your server. A deeper look into the error logs will help you understand where the problem originates from. If it is a server issue, make sure you have enough rights to access your server. Contact your hosting provider to increase your memory limit if you’re running into a space shortage issue. If that doesn’t help, raise a ticket with them mentioning your server issue.
2. Custom code: If your Drupal 6/7 website was more complex than it was expected to be, chances are that instead of assessing for custom code and mapping them properly before the migration, a plain lift and shift was carried out. If you have custom conditions that fire up when your page loads and it does not find the custom code associated with it, you will end up with a broken page. The first thing to do is check to see if you have assessed the website properly in your migration audit (if you did one) to check for custom modules and code. If the problem is because of a custom condition and the code is missing, you will need your Drupal developer to create the custom code implementation. Ideally, the custom code should have been created before any content was migrated.
3. Core/Contrib module: Sometimes you can run into a known issue on your core or contributed module that already has a solution/patch. A little research can help identify this. Find and apply the patch and you should be good to go.
4. Outdated PHP version / libraries: Your new Drupal site might still be running an older version of PHP or libraries that your code depends on. Ensure that your website implements the latest version of PHP and other libraries. Also check if all the system requirements and configurations are met.

Unable to Edit Pages (Permission Issues)

1. 500 error: If you aren’t able to edit pages because you are running into a 500 Internal Server Error, it could be because of various reasons (misconfiguration, bad code, wrong indexing, aggregation, etc.). However, one of the more common reasons is that it could be due to a mismatch between the field formats or missing fields. For example, if your date field from your Drupal 7 site is not migrated in the right format or the value wasn’t transformed to the Drupal 9 format, it will throw an error. Another example is if in Drupal 7 you have been using the Images field but, in Drupal 9, you’re using a media field instead. The best way to fix this is to rectify the migration script to store the data properly. If there are only a few fields to edit, you can also create a hook update.
2. 403 error: Oftentimes, the 403 error is because of incorrect transfer of permissions. Check if permissions are set up correctly. If you’re using a module to manage your users, check if it is available in Drupal 9. Sometimes, you might have hooks or event subscribers restricting access to some users. Check for these conditions and make sure it is implemented in your new installation too.
3. Permissions page is not responding: Your Drupal site might be implementing some custom code to handle permissions. If this code isn’t implemented in the new Drupal 9 site, you might not be able to view or edit (or both) the permissions page. Occasionally we see situations where users were migrated in bulk without properly migrating their roles and user profiles. As a standard practice, before migrating permissions, the developer should be creating custom permissions and assigning them to roles from people/permissions. 

Miserable Website Performance

1. Unnecessary modules: Modules are the building blocks of your Drupal site, so you’ll want to migrate them as well. But sometimes we see outdated unnecessary Drupal 7 modules moved to Drupal 9 which can cause all sorts of problems. Especially since they can weigh down your site. Here are some reasons why some of your modules don’t need to be migrated:
   • The module (or its functionality) has already moved to Drupal Core. For example, the Media contributed module moved to core in Drupal 8.5, which eliminates the need to use the contributed module.
   • Its functionality is simple and can be inserted within another custom module. For example, if a node::postSave module is used only for one or two content types to choose where the user should go once the node is created, it could be possible to move the code to a custom module instead.
   • The requirements for the module needs to be re-assessed. Sometimes, a small change in the usability can hugely improve website performance. For example, all websites do not really need a Content Moderation module unless the content marketing team is big and distributed. Drupal’s core editorial workflow features (Draft, Publish) are good enough for most business requirements that don’t need a complex / detailed workflow.
   • Sometimes, submodules are installed along with modules but are rarely/never used. Such submodules should be removed.
2. Replicating the same architecture: Although it is easier to simply lift and shift and dust your hands off a migration, it is almost never a good approach. Especially if the older (Drupal 6/7) architecture was messy and less robust. A change in the business logic/requirements could also need a complete re-architecture. A thorough site audit will tell you exactly what modules need to be kept and what can be safely eliminated.

Third-Party Integrations No Longer Work

1. Outdated API version: If your website is connected to different third-party tools like Salesforce, Marketo, Mailchimp, etc, an improperly executed migration can affect how these integrations work. Often it’s that the API you’re calling for in the Drupal integration module is an older version. The only fix is that the integration should be written in the latest version of the third-party API.
2. Integration module issues: You will need to check if the third-party API’s are being called correctly in the integration module. Are the parameters being passed appropriately? Check how they are set and retrieved. Check the issue queue for that integration module. There could be a patch available that needs to be applied. Proper testing needs to be done to ensure the API has been properly ported to Drupal 9.

Other Common Issues and Fixes

1. Module installation: Always use composer to install modules. This will avoid errors due to invalid/unavailable dependencies.
2. Migration source mismatch: No matter what your migration source is (CSV, Database, JSON, XML), make sure the source fields match the destination fields. If you’re using CSV as your source, keep the importing order in mind - the priority matters for mapping the content types.
3. Image paths: Many times, users add images directly within the CKEditor content. These images don’t always go to the designated path when migrated because their location is usually different from where the other media files are located. A meticulously planned migration should take care of this issue.
4. SEO: A negligent Drupal 7 to 9 migration can impact your website’s SEO in many ways. One of the most significant issues is broken links. Make sure that the existing URL structure and navigation is preserved as any changes can lead to tons of broken links. A complete SEO audit needs to be done to make sure there are no bumps in the road.
5. Drupal 7 Style: Often Drupal 7 to Drupal 9 migration issues (especially performance issues) emerge because the developers use the same coding style as Drupal 7 instead of adapting to the changes brought in by Drupal 8. Examples, (a) the way you kill page cache is very different in Drupal 8. (b) Drupal 8 has built-in configuration management but it is often not implemented the right way or maintained well in every environment. (c) We have also come across instances where the Drupal 8 project is still implementing procedural code style.