Troubleshooting block themes

When you are building block themes you will run into blank pages, error messages and other mysterious problems. When it comes to 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 solve if you know where to look; here are my troubleshooting tips for block themes:

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?

Make sure 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.

You have two options:
-In the WordPress admin area, go to Appearance > Templates and Appearance > Template parts and delete the item overruling the change to the .html file.

-Or, open the site editor. Select the template or template part you have updated.
Above the content area you will see the template or template part name.
Click on the arrow next to the name to open the template options modal.
You will now see an option called “Clear customizations -Restore template to theme default”.
Select the option, and you will see a confirmation snackbar that says “Template reverted”.
You can also undo the revert.

The template option modal includes a description, a list of  template part areas, and a button with the option to clear customizations and reset the template to the theme default.

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, 
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. Nested block supports, for example style.elements or style.spacing, must have 
matching opening and closing brackets.

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 for it.

To find out if a block has built-in support, you can visit the block reference and list all blocks that has 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