WordPress Debugging 101

This is a case study in debugging WordPress when things go crazy wrong. Here is the problem:

It is really very simple – when I try to upload images to the Media Library it says the file has been uploaded but only a blank thumbnail appears in the Libraries gallery There are several blank thumbnails because I tried various file types – all to no avail. When I copy the image  URL supplied it comes up blank no matter what browser I try to display it with. Ditto when I try to insert the image in a page – it comes up blank. This appears to be a serious bug on the website so I decide to follow a  classic WordPress Debug plan:

  1. Check to see if there is a hack or virus causing the problem.
  2. See if the WordPress core has been altered
  3. Check if the theme is the cause of the problem
  4. Check with Google search,Stack-Overflow, Stack Exchange  and WordPress  for reports of  similar problems
  5. Turn off all the plugins and see if the problem continues
  6. Turn on WP_DEBUG and WP_DEBUG_LOG to see if they uncover error conditions during image load
  7. Check with WordPress colleagues and see if any have encountered this problem
  8. Check with Hosting service for reports of similar problems
  9. Hire a shop for debug services

Now other debugging steps could be taken depending on the nature of the problem; but this  has worked well in the past. So here goes the debug process.

Following the WordPress Debugging Protocol

Now remember this is an informal debugging process whose sole claim to fame is that it has built up overtime and has generally proved successful in the past.

1)Hack Attack Checkup

Checking for a hack attack is easy because I have a WordFence firewall. And  my WordFence firewall scan says NO. But I crosscheck with the free Sucuri Scanner:
Sucuri backs up the the WordFence verdict – NO sign of a hack attack. But this is very strange – The Media Library knows about the attempted image load and is recording all the correct info about the uploaded file – its just not loading an image. For example when I go to to Cpanel:

using the URL supplied by the Media Library – there is nothing there.

2)Check WordPress Core

Again the WordFence scan says there has been no change to the WordPress Core files. But just to be sure I reload the WordPress 4.9.8 version to no avail – images still load as blanks.

3)Check The Theme

This is a simple test, just swapping out the current WordPress theme out and activating the tried and true  TwentySeventeen theme. And again, the blank images problem persists. Now this is raises the stakes because now all the website’s plugins have to be tested. But first a Google search.

4)Check Google search,Stack-Overflow, Stack Exchange  and WordPress

Okay, now we know this is going to be a non-trivial WordPress problem.  So “non-tivial” usually gets reported on Google  and WordPress or the coding help sites like  Stack Exchange or Stack Overflow. I am hopeful someone else has encountered and solved the Media Image Blank problem.  There are some similar problems but none  identically the same. The following are common recommendations:
Reload the WordPress core install – done that already, no go.
In general to fix this problem you have to check the file permissions of your uploads folder (wp-content/uploads). Try to set the numeric value to 755 – tried this using Cpanel and despite a couple of hours of trying various permission settings, the no upload problem persists.  This means having to use the dreaded turn-off plugins debug step.

5)Check For Plugin Conflict

Now checking for a plugin conflict can be a real nightmare depending on the number of plugins used. Unfortunately that is 18 for, For those familiar with  permutational combinatorials using  no repetitions and no order distinction that is  n!/[k! * (n-k)!]  =  18! / [2!  * (18 – 2)!]  =  153 pairs of plugins to be tested. So after turning off 4 or 5 pairs of plugins that are prime candidates for conflict with no luck, I decide to try the all-in approach. This means I  turn off all the plugins and hope for the best. But  images still load as blanks. So plugin conflict cannot be the problem. Uh oh, I am starting to run out of clues as to the nature of the problem. Time to turn to WP_Debug.


Using WP_DEBUG  provides any error message  emitted by the WordPress core. But using it can be  complicated. For newbies to its use, checkout the following excellent tutorial how to.  Now Snapcreek describes the WordPress Debug Log as a friend. But I have scanned through dozens of pages of  debug.log output – not fun. So in signing into my hosting service, I take a precaution and delete the existing  debug.log file before turning  it on again using the WP_DEBUG and  WP_DEBUG_LOG settings in the the wp-config.php for the website. Here are the changes:

And then we tried yet again to load an image into the Media Library with the following result in the debug.log
There was some error messages about a NextGen Gallery RSS setting but those disappeared  when I changed the NGG RSS settings. The bad news – now the problem has  lingered and I had less hope about getting it solved.

7)Check with WordPress colleagues

Fortunately, a Meeting of the WordPress Toronto Fix-It  group was scheduled for the next afternoon – so I signed up immediately. And given the groups ability to solve the first 3 WordPress bugs I was feeling better. But that quickly changed. The meeting members were stunned – none had seen a problem like this. One astute member suggested trying the WP_DEBUG method; but that had already been tried unsuccessfully. So now I would have to try getting help from  Hosting support services.

8)Check with Hosting Support

I was not very confident of this despite the fact that SiteGround support had previously  been prompt and generally found solutions on first chat or email. But those problems were always related to  hosting related services like backup or LetsEncrypt settings. This was primarily a WordPress problem so support could easily beg off. In view of that I made sure that I had well documented a)the nature of the problem and b)all the efforts I had tried to date [most of the screenshots used in this posting]. It certainly helped.

I signed into chat support and immediately got Petar P. on the chat support line. He has a 5 star approval rating and was intrigued by my problem. I think because he thought it would be easy to solve. So I went through a demonstration of trying to upload an image into the Media Library and it coming up blank. We both looked into my wp-contents/uploads directory and could see it was not there. I then described the previous 6 steps taken trying to solve the problem. Petar  asked me to turnoff all the plugins again  – and try an upload. Still no go. But Petar, like me, was intrigued that the MediaLibrary knew everything about the image including where it was “supposedly” stored.

But the session was nearing the 30 minute mark when Support staff get antsy about spending too much time with a single client.  So Petar decided to do a search for the image across the website – Bingo. The file was found in a www folder attached to the bottom of the website. That immediately had Petar thinking that  Media Settings  for the image path was incorrect. But I noted that I did not have control for such settings as shown:
Now here is where the plot thickens. Petar tells me that  is true but there is a way to set the Media Library  using PHP code and that he would do it for me. And instantly the loads to the Media Library now worked.

In the meantime I thought I had seen control for the image path on one of my other sites. But all my websites are  WP version 4.9.8 – so it should not be available. But I had admin open so I decided to take a look:
And surprise, surprise website using WP 4.9.8 does allow users to change the path to the Media Library upload folder. Why does the WordPress 4.9.8 core do two different things in the Media Settings dialog?

I asked Petar but he had no idea what WordPress was up to. But he did have another valuable tip. He said that there were plugins that allow users to create named directories  and suggested that I try one to maintain control over the Media Library upload files. I did  a little research and settled on  the free plugin Media Library Folders which offers a number of added features.

But let me say clearly, kudos are due to Petar P and the SiteGround Technical support staff for providing about 45 minutes of superb and time-saving support.

Lingering Concerns

In effect the operational problem of being able to upload images to Media Library has been solved. But two issue in the background remain. First, when and how was the file path to Media Library uploads changed? I surely could not and did not do it. In the past month I had been trying several different gallery and grid plugins on the website.  Most of the testing of  the plugins used existing images or the NextGen Gallery. So if a  plugin had changed the media Library image path I would not have known it. It was only after using a simple image file uploads to  the Media Library did I discover the problem. But why did the some [or all of the plugins] have to change the image path?

Of equal concern is why is the image path available to me in the Media Settings of WordPress 4.9.8 for some websites but not others. Since I went to the Media Settings in PixofToronto to verify that Media Files were to be organized in month and year based folders – a)I would have a way to spot the problem and b)would have been able to fix the problem myself upon discovering the nature of the problem. Currently, I am adding Media Library Folders plugin to all my own and client websites that do not have an image path field in their Media Settings. Not exactly a best practice.


This WordPress saga is partly about 3 days and 12hours of debugging. It is also about how the classic WordPress Debug cycle actually did not solve the problem. Rather it was the good graces of Petar P with the SiteGround support staff that provided the key insight to the problem – and then an immediate fix and also a long term solution with a Media Library plugin. This is not to say that the classic WordPress Debug Process is useless. Rather, the Debug Cycle has worked very effectively dozens of times for me. But rather this is a statement of direction – as WordPress takes on ever more ambitious functionality and now utilizes syntactically fragile JavaScript as well as PHP[try it, misplace a comma or colon in either JavaScript or PHP code used in WordPress and watch WordPress blow up], episodes of deep debugging may be on the rise.

7 thoughts on “WordPress Debugging 101”

  1. Those are some great tips. WordPress is a very easy platform to use until you have a conflict. Then it can be tricky to resolve the issue. Thanks for sharing,


    1. The problem with WordPress is that it is evolving so fast and making a wrenching transition from PHP to JavaScript on the frontend – so even traditional methods of WordPress debugging are taxed to the limit.

Comments are closed.

Pin It on Pinterest