Troubleshooting block themes

Estimated reading time: 4 minutes

When you are building block themes you may run into blank pages, error messages, and other mysterious problems. When it comes to WordPress block themes and Gutenberg, we still have work to do to improve error handling.

The most common mistakes are simple typos, and they are easy to solve if you know where to look; here are my troubleshooting tips for block themes.

Last updated

Block validation errors

The block validation error is showing identical blocks

If there is a block validation error in the editor, but the expected code and the error is the same, then you likely have a line break or white-space error in your markup that is not displaying in the error message.

Template issues

I made a change to an HTML file, why is it not showing?

Ensure that you have not saved a copy of the template or template part to the database. Templates and template parts that have been updated and saved in the editors take precedence over .html files.

Open the WordPress Site Editor. Next, open the navigation sidebar (click on the WordPress icon or your site icon in the top left corner) and go to the template or template part list.

Items that you have customized will have a small blue dot and an ellipsis menu.
Click on the menu and select “Clear customizations”.

The Site Editor template list shows that the Home template has been customized and the option modal for clearing customizations is opened.

If this fails -did you clear the cache? Are you viewing the correct template?

My template has PHP warnings, what is causing them?

Invalid block support declarations in a template can lead to cryptic PHP warnings on the front of your website, without visible block validation errors in the editor.

Warning: array_key_exists() expects parameter 2 to be array, null given in /var/www/html/wp-includes/block-supports/align.php on line 49

Warning: array_key_exists() expects parameter 2 to be array, null given in /var/www/html/wp-includes/block-supports/custom-classname.php on line 48

Warning: array_key_exists() expects parameter 2 to be array, null given in /var/www/html/wp-content/plugins/gutenberg-git/lib/block-supports/typography.php on line 97

It is easy to think that this template has three separate errors, but it is often one problem, 
which may even be unrelated to the block support that is mentioned (alignments, class names, or typography).

The warning is usually caused by missing quotation marks or missing curly brackets in the 
block comments in your template.
The nested block supports, for example style.elements or style.spacingmust have 
matching opening and closing brackets.

First, check if the error is showing when you are viewing a specific page on your site. If it only shows on one page, then the problem is in the template that you are viewing. If it shows on every page, you want to check your header or footer templates.

Missing template parts

If you test your templates and you notice an error message that says: “Template part has been deleted or is unavailable”, add the theme attribute to your template part block markup:

<!-- wp:template-part {"slug":"footer","theme":"theme-slug","tagName":"footer"} /-->

If your theme name is “fse”, the code would be:

<!-- wp:template-part {"slug":"footer","theme":"fse","tagName":"footer"} /-->

Editor controls are not displaying

I enabled a feature in theme.json, why does the block not have a control?

Editor controls can only be enabled with theme.json if the block already has built-in support.

To find out if a block has built-in support, you can visit the block reference and list all blocks that have support for a feature, or look up a specific block.
Or, view the source of the block.json file in the Gutenberg GitHub repository.

Theme.json formatting errors

The easiest mistakes that we all make in theme.json are leaving an extra trailing comma after a value in a nested setting, missing the comma between settings, or missing quotation marks.
All values except true or false need to be between quotation marks.
Make sure that you have set your code editor or extension to validated JSON files.

Example error message for syntax errors in theme.json:

Notice: Error when decoding a theme.json schema at path ../theme.json Syntax error in ../wp-includes/class-wp-theme-json-resolver.php on line 69