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
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
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”.
If this fails -did you clear the cache? Are you viewing the correct template?
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.
Examples:Warning: array_key_exists() expects parameter 2 to be array, null given in /var/www/html/wp-includes/block-supports/align.php on line 49Warning: 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.spacing, must 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
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