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