Not a valid JSON response

For developers, what do you do when it’s your plugin that’s getting the dreaded “Update failed. The response is not a valid JSON response.” message?

While I was developing my WordPress plugin, I occasionally found that I was encountering the enigmatic “not a valid JSON response” message when I was trying to update my test pages. As you might expect, I headed to Google to find out what this message is and what to do about it. Although I did find a number of web pages that talked about this particular question, but they are invariably aimed at the WordPress administrator who is trying to get their site working. The advice is generally to turn plugins on and off until the problem goes away, and then blame the last plugin they tried. That’s all well and good, I guess, but that’s not very helpful if you’re a developer and it’s your plugin that’s the problem. 

What is the nature of the “not a valid JSON response” error?

This may not be a comprehensive answer, because I can’t say I’ve seen it all, but I can talk about my experience. My plugin uses a shortcode, and I was getting this error any time I tried to edit a page that contained the shortcode.

The problem I was having was that my shortcode was being fired by the editor when I went to save my changes. The shortcode returned some content, and when WordPress attempted to subsequently write some header information, the operation would fail because you can’t send headers after your body content is sent. Now, in my case, the changes weresaved, but the message was disconcerting nevertheless, and WordPress helpfully offered to roll back the changes. Considering that I can’t really reach out to my plugin users, I can’t just say “ignore that” even if I could.

Fixing the “not a valid JSON response” error

The key to avoiding this error is to make sure that your plugin isn’t outputting data at the wrong time. Unfortunately, WordPress tends to try to show the shortcode contents every time the shortcode appears, regardless of whether it’s appropriate or not.

The approach I decided to take was to suppress the shortcode output when the page was being edited. This turned out to be a lot more difficult than it seemed it was going to be.

Step 1 was to add the following line to the very beginning of the main routine of the plugin:

if ( is_admin() ) { return ""; }

This is sort of a standard fix, although it probably does need some clarification because it is an often misunderstood function. is_admin() is true when you are on an admin page, not if you are an admin. There are tests you can make to determine the user’s permissions, but is_admin() is not it!

Now, at first I thought that my problem was solved, but soon learned that editing a page is not covered under is_admin(). Maybe it should be, but that function will return false when editing pages. So, I needed something else.

I tried a few other functions to try to determine if a page was being edited, but it seems that modern block editors such as Gutenberg and Divi really blur the lines between the editor and the viewer, and I couldn’t find a test that I really liked.

So, as they say, I decided to nuke the site from orbit. It’s the only way to be sure. My final line of code reads:

if ( is_admin() || is_user_logged_in() ) { return ""; }

This code uses the is_user_logged_in() function, which is a bit more self-descriptive than the other function. Come to think of it, I suppose the is_admin() call is redundant now, but whatever…

With this code in place, the shortcode is not activated for a logged-in user. Ever. The problem I set out to solve is solved, but there is one unintended consequence is that I can’t see my shortcode in action if I’m logged in at all, even in, say, preview mode. As it happens, this is acceptable to me because I usually edit in one browser and view in another, but it is something less than perfect for my users who might wonder why they can’t preview their stuff. If I find a better solution, I’ll post it here, and if anyone has the answer please leave it in the comments. Thanks!