Back

Debugging the WordPress Block Editor

20 March 2019

Tim Nash

The new WordPress Block Editor (Previously called Gutenberg) has now been around for a month following the launch of WordPress 5.0 and we are excited by the possibilities it brings.

On the whole, migration to the Block Editor has been fairly smooth with few reported issues. Those that have popped up have been around theme and plugin compatibility and these happen with every release.

For the 34SP.com blog, we did find one small bug with the plugin Edit Flow, which we use to give us greater editorial control.

One of the plugin’s features that we use is custom statuses, expanding the options from Publish/Draft etc. to allow us to add ones like “Hands off, chumps” and “I think it’s ready.” We are an assertive bunch!

Unfortunately, custom statuses are not now supported in the Block Editor. In reality, they weren’t in the old one either it was just hacked a bit, and the validation was handled in the backend and as such could be overridden. This means that the API request when saving the post was returning a failure. Since starting this post a new version of Edit Flow has been released and the block editor is now saving.

Debugging in the old world

Historically WordPress debugging has been mostly working with PHP. When something doesn’t work as expected, your first visit is to your PHP error logs to see if there are associated errors. If there aren’t then you might enable WP_DEBUG mode and if you need to use a slightly bigger hammer still, XDebug.

Ultimately tracking down errors is normally a case of following the stack trace back to the plugin or theme.

While there is plenty of Javascript outside of the Block Editor it was rare to need to look much beyond the browser console for issues.

The Block Editor changes that.

REST API and the Block Editor

The Block Editor is semi-independent of WordPress. It is written in Javascript and interacts with WordPress through the REST API. If the Block Editor Javascript wants to change something, it makes an HTTP request normally via the POST verb to the REST API endpoint and waits for the response. The REST API then handles the request and triggers the relevant code, which in turn fires any actions and filters which other plugins and other parts of WordPress core might use. It then returns a response back to the Javascript, which formats it and changes the UI based on the response.

This decoupling means that unfortunately we don’t have a direct correlation between a user pressing a button and the action in response to that. However, it’s also a positive thing as changes can be made both in WordPress Core and the Gutenberg UI of the Block Editor almost independently with the REST API acting as a middle man.

Hello Console

Most modern browsers have a “console” which allows you to see Javascript errors. For this article I’m assuming you are using Chrome but Firefox webtools are also well worth looking at.

To open the console, navigate to the page and then right click and choose inspect element or more directly COMMAND+OPTION+i (Mac) or CTRL+SHIFT+I Linux/Windows, then click on Console.

The console is output generated by your browser while parsing the page and the Javascript on it. It will list any Javascript errors in real time, so if you click a button and it generates an error it will show in the log. It’s worth saying that not every message in the console is an error – normally they are helpfully shown in red. Developers can output content to the console log by using console.log()

Browser extensions might also have entries, too. For example, the adblocker I use indicates which elements were blocked in a list. Likewise, things the browser has done that interact with the page might also show. A good example is if an item is blocked by CSP it will show here.

It’s worth emphasising that a noisy console is generally a bad sign, and a well functioning site should have little to nothing showing in the console.

For Javascript errors the output normally looks like:

Javascript Error in Google Chrome Console

With the error, the line number of the error and the file that the error was generated from.

Great, so this is basically just like the PHP error log?

Unfortunately, we live in the world of minified and concatenated files even on simple sites, so working out which piece of Javascript is actually at fault might prove hard, even with an exact location given.

However, at a simple level, we might be able to identify a plugin and the general error might give us an idea of what’s wrong. If we want to “Prettify” minified code, within the web tools if you click the {} button it will unminify the script making it much easier to read.

Networking tab

With the Block Editor, the most common error we have found (and this was the case for the Edit Flow plugin) was that the page refused to save, saying unable to save.

This seems to be because the REST API has returned an error. To see more, open our Development Tools and click the Network tab, then try saving. A REST API request should appear in the network. Chances are it’s red.

The REST API makes use of HTTP status codes, so when something is successful we can see it in our network tab as a 200 response, when it fails it will normally show as a 400 BAD REQUEST which normally means the data is wrong somehow.

To debug, we can click on the bad request which will show the request headers, and the response headers and body. Clicking Preview will bring back the body payload and if WordPress has rejected the update there should be a JSON payload indicating the error.

Unfortunately, the error will be the description given by the developers which may either be incredibly helpful or totally obtuse. The error for Edit Flow was simply “invalid status” with no other information. It was however enough to realise that it was related to statuses and with that, it wasn’t a huge leap to assume it was the plugin that gives us our cool custom statuses that might be at fault.

Going forward the new Block Editor opens up a lot of opportunities but with its reliance on Javascript at its heart, new support tools are needed to debug even simple queries and our WordPress specialists will be spending much more time looking in their browser consoles and network tabs than they do in clients’ error logs.