How Do You Resolve A WordPress Plugin Conflict?

One of the scariest things that can occur with a WordPress user is that you install a plugin, and upon activation, you get a white screen of death.

This screen, where your beautifully crafted website once lived, is now plain white or produces a line or two of unformatted text.

A plugin conflict is when you have two plugins installed, and while they both work fine, running them together breaks the site.

It usually happens when plugins run in tandem, and they both come packaged with the same or similar library functions. There’s a naming conflict, and PHP produces an error.

This article will discuss how to fix them.

Plugin Conflicts Are Becoming More Rare

First of all, plugin conflict: where somebody installs a plugin that conflicts with another plugin, is becoming more rare.

WordPress, in the last few years, has introduced protections in place that means if an error does occur, rather than activate the plugin fully, it’ll backtrack automatically, provide an error, and leave the plugin deactivated.

For the majority of users, this is what they see.

At this point, an investigation should be done in a staging environment with this plugin, but unless it’s a unique plugin, an alternative may need to be found that doesn’t conflict with your setup.

Plugin conflicts tend to occur when you install a Must Use (MU) plugin via a service like FTP, an update to one or more plugins takes place, or you have a custom plugin activated and changes are pushed to the server.

I’ll walk you through my process of resolving plugin conflicts.

Do You Have Access To WordPress?

To begin, the first question you should ask is if you have access to WordPress.

If you do, conventional wisdom dictates that the course of action to take is to deactivate all plugins and switch to a default theme, to try and troubleshoot where the problem occurs.

If you are doing this on a live site, this isn’t ideal, as the site may still have a lot of functionality.

A different approach is to install the Health Check and Troubleshooting plugin. Installing this plugin would allow you to run a version of the site with a default theme, and no plugins installed.

Simply activate each plugin in turn until you identify the one that is causing the issue and then leave that one deactivated.

Make sure the theme is the last thing activated, as custom themes could use functionality in plugins that could bring down the site.

If You Don’t Have Access To WordPress

If you don’t have access to WordPress, then there could be a bit of a process in order to diagnose and fix the problem.

This approach is what I take as best as I can when diagnosing plugin conflicts. It can be done in any order, depending on your knowledge and what you have access to.

Have Access To The Administrative Email? You May Get An Email

If you have access to the administrator email with WordPress (set in Settings > General), you may receive an email.

This will allow you to put the site into Recovery Mode. From there, you can log in, and it will identify the plugin that has the issue, and you can deactivate it.

Check The Hosts’ Log File

The first step would be to check the host’s log file.

Depending on the host, it may be easily visible in your host’s dashboard or from within cPanel, but if you only have a file browser, they tend to be put outside of the /public_html/ or /www/ (which are publicly available). Usually, one level up in a file called /logs/ tends to be where it’s located.

Should you find the file (it should have a name like error_log), download it and search for any Fatal Error within the document, maybe towards the bottom.

Within the error message, you should have a couple of file locations that will dictate where the file issues occur.

No Logs? You May Need To Activate Them

If you have FTP/SFTP access to the site but no logs, you may need to activate them.

Within the root directory of WordPress, add the following lines to the wp-config.php file.

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

This will create a file debug.log within the wp-content/ folder. From there, you can see the errors in this file.

Security Tip: The debug.log will be publicly visible, so once you’ve fixed the issue, remove these lines from wp-config.php and delete the debug.log file.

Resolving These Plugin Conflicts

Whichever method you use, your logs should produce lines like this below:-

Fatal error: Cannot redeclare hello_dolly_get_lyric() (previously declared in/wp-content/plugins/broken-plugin/index.php:17) in /wp-content/plugins/hello-dolly/hello.php on line 46

Each element means:

• “Fatal Error” determines the error. A fatal error in PHP means that the site immediately stops working. You can get other errors or warnings.
• “Cannot redeclare hello_dolly_get_lyric()” is the fatal error. In this case, there are two PHP functions with the same name (hello_dolly_get_lyric()). This is the basis of the plugin conflict.
• “/wp-content/plugins/hello-dolly/hello.php on line 46” tells you where this error occurs. While the line number isn’t important (unless you’re coding yourself), it does tell you the plugin where the plugin error occurs – in this case, “hello-dolly”.

The next step is to manually change the plugin.

In your chosen FTP programme or file manager, go to the plugin folder within WordPress – /wp-content/plugins/ in this case – and rename the plugin folder (in this case, change “hello-dolly” to “broken-hello-dolly”). This will deactivate the plugin when you next log into WordPress.

It’s a good idea not to delete the WordPress plugin if you can prevent it. This will force the deactivation of the plugin in question.

From there, you can investigate the two plugins and identify why the two functions are called twice.

For Developers: Good Practice Can Prevent Plugin Conflicts

If you are a developer building WordPress sites, following good practice can prevent plugin conflicts.

Here are some tips for preventing your plugin or WordPress sites from having plugin conflicts with other plugins out there:

1. If you are not using PHP Namespaces, then I’d recommend naming your classes or functions with a prefix. Something like plugin_name_function_name can prevent similar functionality from having the same function name. Try to make them unique (so don’t use wp_ as a prefix).
2. Using function_exists around your functions to prevent your functions from loading if they already exist.
3. If you are importing functionality, using class_exists can check to see if the class has already been loaded.
4. Loading your functionality late, so naming your plugin folder with a late alphabet letter is useful. Not every developer follows the same approach as you!
5. If you are building on one site, make sure your server setup is the same (or as close to being the same) as the live environment.

You’re never going to completely guarantee your plugin or theme doesn’t conflict with the millions of plugins that exist in the WordPress space.

However, by following the above steps, you can minimize conflict as much as possible, and simple changes to your code writing can prevent a world of debugging hell later.

More Resources:

---

Featured Image: Whiskerz/Shutterstock