Debug a wordpress plugin or theme – for non-developers

It works for others, but not for you – what’s happening?

picture of a dead bug and blood
Don't sweat blood over a bug

Rules for dealing with a  new plugin, or theme or an upgrade:

  • READ the instructions, okay some plugins can be intuitive, but some may need a crucial step.  Go back and check that you have not missed something
    • Check the readme.txt (or the WordPress.org site – shoudl be the same)
    • Check the plugins own site
    • Check the settings.
      • I like to code my plugin in such a way that you do not have to even look at the settings, it should still work with a default setup, but not everyone does – some people do not even check the settings.  Some developers put their settings in strange places – I found one whose settings were reached off the plugin listing line, but only when you hovered over the plugin line!
      • I also tend to put some explanatory text, or links to explanations in the settings area near the relevant area
  • READ the changelog.  If the author is diligent, there should be detailed description of the changes.  If there is no detailed description, assume anything could have changed.  If it says ANYTHING about a database change,you definitely need to
    • switch maintenance mode on – a number of plugins can do this for you
    • do a backup that includes the database, and know how to restore it!
  • If the plugin is crucial, check the forums BEFORE you upgrade. If you are really unlucky you may be the first to flush out a bug or clash, but the odds are someone will have got there before you.
  • Test the new plugin, theme or upgrade on a test server first, with other crucial plugins active. NEVER ever apply it to your live site straight off, even if you trust the developer.  There are infinite combinations of circumstances and your site may just find one that breaks the plugin.
  • Have a backup that YOU know how to restore.   Yes it seems it is  not obvious to all, but it is  no good having a backup if you have no idea how to use it.  Hopefully your host has a simple option for you – be aware of lead times if you need their input.
  • Do not start late at night.  If you hit a problem at past 10pm at night, stop, reverse, go to bed. (Yes I’m a mother, but I also know when I am not  being effective.  I do not like to waste my time.)

Only break these rules if…

you are able to cope with the consequences of  a problem

  1. simple actions you may need to do could be  to get the prior version of the code and ftp that over the ‘new’ version
  2. worst may be having to reverse an updated database (and no backup),
  3. or have the plugin deactivated for a while.

Debugging the plugin or theme on your site

If it is a simple, obvious problem or visible error, a “fatal error”, “warning” or “notice”, then an internet search, or forum search both at wp and at a plugin own site,  using the words but removing anything that relates to your site can be very useful and give you a quick sense of what may be wrong. It may educate about the WordPress functionality is use.

Common things are :

  • permalinks needing flushing with custom post types and taxonomies,
  • missing a wp function  due to an old wp install,
  • function or class naming clash with a theme or another plugin
  • etc

Not a simple, obvious problem, or plugin developer cannot recreate the problem?

If it is not a simple, obvious problem or a visible error, then you may need to do one of the following. Both  are looking for a clash or trying to isolate the circumstances that cause the problem

  1. Go backwards – Either start with your test server and switch off  plugins, one by one,  testing the plugin in question after each step, or
  2. Start at the beginning and go forwards – start with a clean install and add in the plugins and themes one by one

This may seem cumbersome, but sometimes it is the only way.  It can also be highly informative about the plugins you are using and/or the theme.  before you all of this, though check first:

  • Is it an old WordPress? If yes, try on a new clean install with latest
  • Did you just upgrade to latest WordPress and was it just released ?  the plugin may not yet be compatible with something that changed in WordPress.
  • It is the php version?  the plugin should work on the ‘most’ common php version, which at time of writing is 5.2  See http://wordpress.org/about/stats/.  If your php is old or very new, this may be it. You need to be able to tell the developer what php you are using.

Be methodical

Be careful that you are doing the necessary steps to adequately test at each step, so you do not waste your time. Do you need

  • refresh the browser and /or clear the cache’
  • logout / login (depends on the functionality of the plugin)

The objective

You want to be able to honestly tell the developer that you have tested the plugin on a

  • clean (non customised) WordPress install, preferably with the latest WordPress version
  • with the current default theme (eg: twentyten) and
  • no other plugins active (or maybe only standard plugins active)

It is highly unlikely that you will get  to this point without  finding some thing out. Examples:

  • a clash with a theme or other plugin
  • if it worked on a clean new wp install, it may be that your database or your WordPress is corrupted. Scary, does happen.  Sometimes even a clean WordPress install gets corrupted and one has to “install” it twice.  I’ve seen people describe this.

Reporting a problem – the rules of engagement

  • Do NOT struggle for multiple hours, getting more frustrated.  Take a tea break, go for a walk, get a nights sleep.  Check for environment changes… i’ve seen people curse WordPress and a developer only to shamefacedly report back after a day or so to report why it was actually something that had happened on their side.
  • Report early to the plugin forum – you may be highlighting something new, the sooner the developer knows, the quicker they can address it.  Use some good judgement about how early to flag an error, but do continue with the debug steps.
  • BUT DO not report without doing some of your own debugging.  Your situation may be unique.
  • Be specific – report  with as much information as possible .   “It does not work” is not helpful to anyone.  Clearly it will have worked for some people or most likely many. The more info you can provide, the more likely you will get quick resolution.
  • Unless you have a support contract with a guaranteed response time, do not realistically expect better than a 48 hour to 1 week turnaround, or even one at all in the case of free plugins or ones that explicitly exclude guaranteed support. It doesn’t mean that they do not support it, it just means they are unable to guarantee it – this is quite reasonable – particularly if the the developers are a small organisation or an individual. For example most of you know that  I usually get to a question within hours, but cannot guarantee that, so I explicitly exclude guaranteed support in my terms.
  • When reporting, have good manners and remember timezones.  You never know what is happening in someone else world (births, deaths, tsunamis, earthquakes, snake bites, sick children, broken fibre optic undersea cables, loss of power, loss of internet…) .

Debugging for plugin developers

Most of the above applies to you too! however there is more. Mostly I recommend

  • always working with php and mysql  ALL errors, warnings, notices etc switched on.
  • test on multiple platforms and browsers
  • before releasing an upgrade, test on existing (upgrade) and one new clean install

For more details, see

Update all plugins
It's tempting.. but should you?

Judge the risk/benefit tradeoff before you click that one step upgrade all – you are the one responsible!