7 reasons for malfunctioning plugins (and their fixes)

It happens to every plugin author: you receive emails from people that your plugin isn’t working. There are about 7 reasons that – for me – seem to be the root cause of up to 95% of these emails, and I thought I’d write them down and show you how I try to handle them.

1. Missing hooks

It annoys the *peep* out of me when I find out that my plugin is in fact working fine, but the *peep* theme author didn’t think it necessary to add a wp_head or wp_footer call. This happens more than you’d think, but in most cases you can’t really blame the user in question, the theme author is just a moron. For your reference: the wp_head() call needs to exist right before the closing </head> call, and the wp_footer() call should be right before the closing </body> tag.

I used to check for this in my plugin, but the code doing the check caused even more problems, so if you have a good solution for this, that’d be appreciated. I personally think WordPress shouldn’t even activate themes without these two hooks.

2. A caching plugin

If you’re looking at a cached version of a page, and you’ve just installed or reconfigured the plugin, chances are the changes aren’t reflected in the output yet. In my Google Analytics plugin, I’ve actually added cache clearing code for W3 Total Cache and WP Super Cache, if you’re a plugin author you might find it useful:

<?php
if ( function_exists('w3tc_pgcache_flush') ) {
  w3tc_pgcache_flush();
} else if ( function_exists('wp_cache_clear_cache') ) {
  wp_cache_clear_cache();
}
?>

This is only necessary to do after you’ve saved settings that would change the output of your plugin of course.

3. You’re not supposed to see anything

My Google Analytics plugin has the option to hide the tracking code for certain user levels. Turns out that, when you enable this feature, you’re actually not seeing anything at all in the code. That’s a good thing, right? Wrong. It meant dozens of emails coming to me in the course of like 6 months, until I was smart enough to add the following message to the output of my plugin for those users:

echo "<!-- Google Analytics tracking code not 
  shown because users over level ".$options["ignore_userlevel"]." 
  are ignored -->n";

Remember that when people use W3 Total Cache’s minification feature, they won’t even see this. The solution is to wrap it in CDATA tags.

4. You have to actually enable the plugin!

Seems obvious right? Well it doesn’t always seem to be. I get this email about once every 2 months “your plugin doesn’t work, it’s shit. Help me fix it” (sometimes they’re nicer, oftentimes they’re worse :) ). The best part is when it’s followed, like 5 hours later, by “ehm I actually forgot to activate your plugin”. Happens to all of us, you know.

5. You haven’t configured the plugin yet

There’s a reason my plugins now scream at you to configure them as soon as they’re activated: I got emails saying it didn’t work, when the person emailing simply hadn’t even configured the plugin yet. Yeah I know, my plugin should be able to just guess what your analytics account is, I’d love to be able to, but alas… So, especially for those people who think I have magic skills, there’s now a warning in the admin:

Not configured warning

And a notice in the source output:

echo "<!-- Google Analytics tracking code not shown because
  you haven't configured the plugin yet. -->";

6. You can’t change the settings

Either you’re blind or another plugin is malfunctioning, but you can’t find the settings page for the plugin you want to configure. Luckily, WordPress has you covered (and yes, some people think that emailing the plugin author is the solution for that). Go to the plugins page, and click on the Settings link for the plugin:

That is of course, if the particular plugin actually was kind enough to include that link… For some reason, some plugin authors seem to think these standards don’t have to be adhered to. They deserve to get more email.

7. The plugin is incomplete

When you uploaded the plugin, you might have missed a file, or two. Or the upload went bust. Or the auto install went bust. It happens. I haven’t had to build in a check for this yet, since my plugins aren’t that big usually, but I noticed this in W3 Total Cache most recent changelog:

Added an additional notification to help users identify 
  incomplete installations upon activation.

That shows you two things: A, Frederick knows what he’s doing and prevents people from emailing him over issues like that, B, it happens more often than you’d guess.

Your experiences

All the code examples above have been added to my plugin after several support requests for that particular issue. They might save you a fair bit of time if you’ve just started developing plugins, so feel free to use them. I know a fairly large portion of my readers dabbles with this stuff themselves, I’d love for you to share your experiences in the comments!

Tags:


Yoast.com runs on the Genesis Framework

Genesis theme frameworkThe Genesis Framework empowers you to quickly and easily build incredible websites with WordPress. Whether you're a novice or advanced developer, Genesis provides you with the secure and search-engine-optimized foundation that takes WordPress to places you never thought it could go.

Read our Genesis review or get Genesis now!

40 Responses

  1. RarstBy Rarst on 31 August, 2010

    Another quite common malfunction is when plugin author forgets to exclude his stuff from working/showing on admin pages. So front end is peachy, but admin area is suddenly full of esoteric bugs and it is not obvious to make a leap from that to recently installed plugin.

    • Joost de ValkBy Joost de Valk on 31 August, 2010

      Been there, done that and got the t-shirt, good one indeed :)

  2. John GarrettBy John Garrett on 31 August, 2010

    I notice number 6 a lot. I’m less than a year into WordPress, but I found it odd that many plugins don’t have a link right to the settings page. I didn’t know it was supposed to be a standard. Man does that save time and says a lot about the plugin author.

    • Joost de ValkBy Joost de Valk on 31 August, 2010

      A “standard” is maybe too big of a word, but most plugin authors now do it, and I think everyone ought too. I don’t think we’ve ever formalized anything about how plugin backends should look.

      • Dave DoolinBy Dave Doolin on 8 September, 2010

        This needs to be a standard call instead of the current clunky array setup. But I’m probably missing something, and will look into it further. Opportunity to create my own wrapper for that matter.

  3. PatrickBy Patrick on 31 August, 2010

    Hi

    I just started uploading some plugins into a brand new WP 3.0.1 site. My last one was your excellent Breadcrumbs plugin. However, for some reason, I now get a blank white screen when I go to my Plugins in the dashboard (at file plugins.php). I can go into ‘Add New’, but I am shut out from the regular Plugins area. Has anyone seen this or know of any ways I can correct this? Many thanks.

    Patrick

    • Joost de ValkBy Joost de Valk on 31 August, 2010

      Check out the solutions in this post, and check out my recent post about WordPress debug modes.

      • PatrickBy Patrick on 31 August, 2010

        Nice! Thanks for the reply – just what I needed.

  4. Greg WiniarskiBy Greg Winiarski on 31 August, 2010

    I think i am guilty of #1 :), although i at least for now develop themes only for my own use, so i guess that’s somewhat fine.

    On the other hand a lot of support requests i get is caused by caching plugins exactly like you described it, but then again non-technical user has no idea what is happening, so it’s kind of unfair to blame them.

  5. Craig BakBy Craig Bak on 31 August, 2010

    So if you’ve checked with these fixes and everything you see is ok, but still find that the plugin you were using on say WP2.8 is now not working (even especially in Admin to configure it) after upgrading to WP3.0, what would you say the most probable cause for that would be?

    I cannot ask the author as they do not support it any longer!?!

    Thanks,
    Craig – The 7thDwarf

    • Joost de ValkBy Joost de Valk on 31 August, 2010

      If a plugin isn’t maintained and isn’t working and you’re not able to fix it, your best bet is to find another plugin that does the same. If something breaks now, it’ll break even worse in 3.1, 3.2, 3.3 etc.

      • Craig BakBy Craig Bak on 31 August, 2010

        Thanks Joost,
        But what is the possibility that it may just be something that can be easily fixed and taken over as the new owner?
        Do plugin authors take-on other authors’ work when abandoned or should it just be made from scratch by asking for someone to code it for you, especially when the plugin is a premium (paid) plugin that has a certain amount of userbase already?

        Regards,
        Craig

        • Joost de ValkBy Joost de Valk on 31 August, 2010

          Depends entirely on the license and stuff like that. If he’s not maintaining it anymore, and it’s GPL, email it to me and I’d be happy to have a look at the whole thing :)

          • Craig BakBy Craig Bak on 31 August, 2010

            Thanks again mate,

            I’ll get it sorted for you to look at.
            Your help is greatly appreciated!!

            Craig

  6. PaulBy Paul on 31 August, 2010

    I develop my own theme for my blog and had a problem with a plugin. Turns out it was because of point #1. At least I learned from my mistake and will always include both the wp_head and wp_footer calls.

    I notice a few plugins now provide an option, or automatically, clear the cache for the W3 Total Cache plugin. I like this feature as I don’t have to worry about clearing the cache manually. One thing I do like about the W3 Total Cache is how it displays a message asking me to clear the cache when something changes – well coded plugin for sure.

    • Joost de ValkBy Joost de Valk on 31 August, 2010

      The finesse in W3 Total Cache constantly pushes me to up my game… Frederick is setting some very high bars for good plugins there.

  7. LeeBy Lee on 31 August, 2010

    I install the PHPurchase Ecommerce plugin on a lot of sites. It has an inventory tracking feature that uses ajax to check inventory before adding a product to the cart. One of the biggest problems I see on people’s sites that they have jQuery conflicts (or other javascript errors) that cause all things AJAX to break on their site. The solution is often to make sure you use jQuery in no conflict mode.

    • Joost de ValkBy Joost de Valk on 31 August, 2010

      Good one, indeed. Worst is actually when they load both Prototype AND jQuery, not only does that lead to JS errors, it also leads to performance hits. WordPress developers should learn to stick with jQuery.

      • twincascosBy twincascos on 1 September, 2010

        I’d have to take issue with this statement.
        Wordpress backside does use jQuery. But the front side can use any framework.
        I have lots of user issues with multiple js frameworks on their site. Many plugin devs don’t id the framework they are using for the user to know if they will have a conflict.
        All of my plugins use mootools. And they work great… except when a user has jQuery, and prototype already being loaded.
        All the same … WordPress developers should learn to stick with Mootools, … just kidding, they’re all good, when taken one at a time.

  8. Ramon FinckenBy Ramon Fincken on 31 August, 2010

    In addition (also from my own experience) :

    a) The plugin leans heavy on old/depreciated/removed WP core code
    b) The plugin is just crap :)
    c) The plugin relies on a wp_head(); and / or wp_footer();
    I’ve seen themes ( mostly done by bad templaters ) that do not have these calls.

  9. AminBy Amin on 1 September, 2010

    Clearing the cache after saving the settings is a good idea.. thanks heaps for sharing the code! I have been instructing my customers to use the W3 Total Cache plugin which is making my life a lot easier (couldn’t thank Frederick enough for developing this plugin).

    I get a lot of emails telling me the “Plugin does not work” (which btw does not give me any information to troubleshoot) and when I check their site I find that their PHP session is not working (I use the session for my shopping cart). It’s surprising how many hosting companies sell hosting where the PHP session isn’t even configured correctly! Would be good if there is a piece of code I can use that tells the plugin if PHP session isn’t working on the server.

    I agree that a theme shouldn’t even be allowed to be activated if it’s missing the vital “wp_head” or “wp_footer” calls. It got to a stage that I had to write a post (http://www.tipsandtricks-hq.com/?p=2270) and direct my customers to that post for the full explanation.

  10. Big BiffsBy Big Biffs on 1 September, 2010

    Hi Joost,

    I heard that you will be releasing your own version of SEO plugin. When can we expect this?

    I have been using SEO Ultimate

    Thanks!

  11. Danny van KootenBy Danny van Kooten on 1 September, 2010

    Thanks, provides some good points plugin developers should think about to decrease the amount of emails from users hehe. :)

    Would be nice if WordPress included a simpler way to add the settings link (#6) to the plugin’s admin panel. Like making it possible to add another comment line to the plugin’s main file that provides the settings-slug, and when not given, don’t show. Well, maybe it is just me being lazy. ;-)

  12. Daniel HaimBy Daniel Haim on 1 September, 2010

    Joost, your plugins are awesome! Don’t let anybody let you down haha.

    Can’t agree more about the wp head and footer closing should be a must for all themes.

  13. TrafficColemanBy TrafficColeman on 1 September, 2010

    Hi Joost,

    You know just as well as I, that most people are not that smart when it comes to plug. Usually its’
    always the newbie who have these problems…so its good you put this post together for
    those who can’t figure out simple stuff.

    “TrafficColeman “Signing Off”

  14. Andy BaileyBy Andy Bailey on 1 September, 2010

    some more juicy user errors…

    * trying to install it on wordpress.com
    * trying to use it on an unsupported system (comment plugins that don’t work with disqus/intense debate
    * Not reading important instructions BIG BOLD SENTENCES on the download page or in the readme (or even on the settings page)
    * Completely misunderstanding names of fields in the settings page – ie. Form settings / name field <– user puts their own name in there instead!

    I could go on and on, in fact, I'm considering writing a book on user errors!

    They're annoying but, even if a stupid, easily correctable, shouldn't-have-happened-if-you-read-the-download-page error can mean the plugin coder can change something to prevent it from happening.

    I agree with you about wp_head and wp_footer though, a theme shouldn't be able to be activated if it doesn't have them!

    • Dave DoolinBy Dave Doolin on 8 September, 2010

      I’ll buy your book, Andy. Please write it.

  15. AlexBy Alex on 1 September, 2010

    Hi Joost

    Thanks for such a useful post. Can I look forward to another post called “7 reasons for malfunctioning Themes (and their fixes) ?”

    :-)

    Alex

  16. Kenneth YoungBy Kenneth Young on 1 September, 2010

    When it comes to plugins I am so afraid that I will break them and the notice that plugins should
    not be tempered with doesn’t help any either. I just so do not understand these things.

    Kenneth

  17. MarcusBy Marcus on 1 September, 2010

    Sometimes, we devs probably do deserve the load of support mails we get for the common mistakes made :)

    Another couple of common issues:

    1. Some plugin devs actually include their own version of jQuery instead of loading the integrated JS file. Or using another library. These both can cause conflicts and break all the JS on the site.
    2. Not adhering to WordPress Coding Standards (I am guilty of this, learnt my lessons from all the emails!)

    By the way, how do you get the settings link to show on the plugins page?

  18. Jim MunroBy Jim Munro on 1 September, 2010

    A good option I don’t see is my first line of defense when a plugin doesn’t work: go back to WordPress.org and view the forum link in the plugin page (the part that says “What Others Are Saying”). Often times the biggest problems are posted by others here and you can find out whether it works (or not) with the latest version or whatever issues people are having with it.

    I don’t think I’ve ever emailed a plugin author yet for help with a plugin, because of this. ;)

  19. Cheryl MacNaughtonBy Cheryl MacNaughton on 1 September, 2010

    Do you have a solution for why FeedBurner is unable to see the RSS feed and gives an “Error getting URL: 404 – Not Found”
    I have searched the forums for an answer and been unable to determine how to fix this.
    I have WP-Feedburner plugin activated.

  20. imran khanBy imran khan on 3 September, 2010

    well this is a very useful post in detail!!! i face these issues .. Thanks alot

  21. IsabellaBy Isabella on 3 September, 2010

    Thanks for such a nice and useful post. The plugins points are awesome. I have faced problem
    no 6 but i have just started wordpress so it was difficult me to resolve this issue. May be from
    your post it will help me to sort out this issue.

  22. AskApacheBy AskApache on 7 September, 2010

    In my experience, 50% of the problems with plugins are due to poor plugin design/coding (who has time to code that much?). The other 49% of the problems are basically user-inflicted due to total complete lack of any computer skill. The remaining 1% of problems are version-compatibilities.

    BTW, your site is looking really sharp, I haven’t been here for awhile and am impressed with all you are getting done. This article was pretty unhelpful to an author like me, but great in terms of seeing a best-practices blogger in action, keep it up Joost!

  23. Michael FeverBy Michael Fever on 7 September, 2010

    I think its best to disable all IE and FF plugins and just use Chrome. Don’t even launch those other 2.

  24. Dave DoolinBy Dave Doolin on 8 September, 2010

    I’ve also recently had a class conflict with another plugin. Which is something I need to handle soon.

  25. SitebaseBy Sitebase on 11 September, 2010

    I noticed that some plugin developers are using php shorttags.
    This will result in a not working plugin because this feature is disable on many servers.

  26. MotivatoryBy Motivatory on 15 September, 2010

    I am loving this post and the information here will be of great help to improving my blog in no little way. thanks a million.

  27. Get Business OnlineBy Get Business Online on 24 September, 2010

    After installing wp-minify, some things stopped working for me. I’m not sure why, but after excluding those plugins’ JavaScript from being minified, they cam back to life.

    Since Google Page Speed, I thought plugin authors would check something like this and/or the author of the minification plugin, but it’s not a perfect world and they don’t always do what I expect ;)