If you’ve seen this message in the WordPress Site Editor:
“Your site doesn’t include support for the ‘namespace/block-name’ block. You can leave it as-is or remove it.”
…you’re probably scratching your head wondering what went wrong — especially if you just registered a custom block and added it to a template.
This guide walks through why this error happens, how to fix it using current block development best practices, and how to future-proof your custom blocks using block.json.
🔍 What the Error Means
This message appears when the block editor encounters a block it can’t find — often because WordPress doesn’t know how to render or load the block on the backend.
This usually happens when:
- A custom block is referenced in a block-based template (like
index.html) but hasn’t been properly registered. - The block’s JavaScript or PHP logic isn’t loaded in time (or at all).
- The block is missing or incorrectly declared in your theme or plugin.
- You’re using outdated or partial block registration code.
📦 Example Scenario
You create a block and add it to a template like this:
<!-- wp:mytheme/project-navigation /-->
But when you load the Site Editor or preview the page, you get:
“Your site doesn’t include support for the ‘mytheme/project-navigation’ block.”
This means WordPress doesn’t recognize the block name mytheme/project-navigation — either because it wasn’t registered, or it was registered too late.
✅ The Modern Fix: Use block.json
To ensure your custom block is fully supported, use block.json — the current standard for registering blocks in WordPress.
Why block.json?
- Registers the block with metadata
- Loads scripts, styles, and render files
- Makes blocks discoverable by the Site Editor
- Works cleanly with block themes and FSE
🧱 Example Block Setup
Let’s create a block that adds Previous/Next navigation to custom post types like Projects.
📁 Folder structure:
/theme
/blocks
/project-navigation
block.json
index.js
render.php
1. block.json
{
"apiVersion": 3,
"name": "mytheme/project-navigation",
"title": "Project Navigation",
"category": "widgets",
"icon": "leftright",
"description": "Adds Previous and Next links to single Project posts.",
"editorScript": "file:./index.js",
"render": "file:./render.php"
}
2. index.js
import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
import { registerBlockType } from '@wordpress/blocks';
function EditProjectNavigation() {
const props = useBlockProps();
return (
<div {...props}>
<p>{__('This block will show previous and next project links on the front end.', 'mytheme')}</p>
</div>
);
}
registerBlockType('mytheme/project-navigation', {
edit: EditProjectNavigation,
save: () => null // Rendered server-side
});
💡 Define components before calling
registerBlockType()to avoidReferenceErrordue to JavaScript hoisting rules.
3. render.php
<?php
function render_project_navigation_block( $attributes, $content ) {
if ( ! is_singular( 'project' ) ) {
return '';
}
$prev = get_previous_post_link( '%link', '← Previous Project', true );
$next = get_next_post_link( '%link', 'Next Project →', true );
return sprintf(
'<nav class="project-nav">%s %s</nav>',
$prev ?: '<span class="no-link">No previous</span>',
$next ?: '<span class="no-link">No next</span>'
);
}
You can use any logic here — this example only renders on
projectpost types.
4. functions.php (or your plugin file)
add_action( 'init', function() {
register_block_type( __DIR__ . '/blocks/project-navigation' );
});
No need to manually enqueue JS or register render callbacks — WordPress reads everything from block.json.
🧪 Troubleshooting That Error
| ✅ Checklist | Details |
|---|---|
| Block name matches? | The name in your template (e.g. <!-- wp:mytheme/project-navigation /-->) must match block.json. |
| JS/Render files exist? | Are index.js and render.php actually present and error-free? |
| Scripts loaded early enough? | Don’t delay block registration with late hooks. |
Any typos in block.json? | Even small issues can prevent the block from registering. |
| Site Editor reloaded? | Sometimes a browser hard refresh is needed to pick up new blocks. |
✅ Summary
If you see:
“Your site doesn’t include support for the ‘*’ block.”
…it means the block editor can’t recognize your block.
To fix it:
- Use
block.jsonto register your block cleanly - Make sure all assets (JS, PHP, styles) are declared and loaded
- Match the block name exactly in your templates
- Avoid hoisting issues in JS (
constvsfunction)
📚 Helpful Links
Let me know if you’d like a working example or have a specific error trace — happy to help debug!