WordPress Block Template Not Applying? Check the Database
Get WordPress serving your theme file again when a block template is not applying: clear the Site Editor copy in the database, then check filenames.
Your template file is almost certainly being ignored because a copy in the database is winning. The moment you open a template in the Site Editor and press Save, WordPress writes a wp_template post record, and from then on that record is served instead of the .html file in your theme folder, so every edit you make to the file afterwards is invisible on the front end. Deleting that record is the fix, and it is the first thing to check before you touch the hierarchy, the filename, or the cache.
TL;DR: Open Appearance → Editor → Templates and look at the template’s options menu. If it offers Reset, a saved copy in the database is overriding your file, and Reset hands control back to the file. If the menu offers neither Reset nor Delete, nothing is saved over the file, and it is time to check the filename, the hierarchy, a leftover PHP template, or the cache.
Confirm the database copy exists
Go to Appearance → Editor → Templates and open the options menu (the three dots) on the template that is not applying. In WordPress 7.1.4 the actions on that menu tell you where the template comes from:
| What the template is | REST API source and has_theme_file | Options menu offers |
|---|---|---|
| A theme file nobody has saved over | theme, true | Neither Reset nor Delete |
| A theme file with a saved copy in the database | custom, true | Reset, which deletes the saved copy |
| A template created in the Site Editor, with no file | custom, false | Delete |
| A plugin-registered template with a saved copy | custom | Reset |
The source and has_theme_file values come from a run on 2026-11-16 in WordPress Playground (WordPress 7.1.4, PHP 8.3, Twenty Twenty-Five), reading each template through the REST API the Site Editor uses. The menu rule is read from the editor script that ships with WordPress 7.1.4, and the Reset case matches the screenshot below. We did not click through the Delete case.
You can check the same thing from the command line, which is faster and works even when the Site Editor is misbehaving:
wp post list --post_type=wp_template --fields=ID,post_name,post_status,post_title
wp post list --post_type=wp_template_part --fields=ID,post_name,post_status,post_title
Each row is a database override. The post_name matches the template slug, so a row named single is shadowing templates/single.html.
One detail that trips people up: these records are tied to a theme through a taxonomy term, not through a path. If you rename your theme’s folder, the saved templates stay in the database but stop matching the active theme, and the site abruptly falls back to files. That looks like “my customizations vanished” rather than “my file is ignored”: same mechanism, opposite symptom.
Clear it
In the Site Editor, open the template’s options menu and choose Reset. That deletes the database record and control returns to the file on disk.

If the menu offers Delete instead of Reset, that template exists only in the database and has no file behind it. Deleting it removes the template entirely and WordPress falls back down the hierarchy.
We checked the mechanism itself through the REST API, on 2026-11-16 in WordPress Playground (WordPress 7.1.4, PHP 8.3, Twenty Twenty-Five):
| Step | Action | Result |
|---|---|---|
| 1 | Read the page template, never edited | source theme, has_theme_file true, no database post (wp_id 0) |
| 2 | Saved a change to the single template, as the Site Editor’s Save does | source custom, has_theme_file true, a new wp_template post (wp_id 5) |
| 3 | Created a new template, odie-landing, with no file | source custom, has_theme_file false |
| 4 | Sent DELETE for both, without force, which moves a saved template to the trash | single back to source theme with wp_id 0; odie-landing returned rest_template_not_found |
The Site Editor’s own buttons go further than our test did. Reset saves the template with source set to theme, and the REST controller answers that by deleting the saved copy permanently. Delete sends DELETE with force: true, which also deletes permanently instead of trashing (both read from the WordPress 7.1.4 source, not run). Either way the file takes over again.
From WP-CLI, using an ID from the list above:
wp post delete 482 --force
Reset has a cost: it permanently discards whatever you built in the Site Editor for that template, and it cannot be undone. If the Site Editor version has real work in it, copy the block markup out first. Open the template in the editor, switch to the code view, and paste the result into your .html file. That way the file becomes the source of truth and nothing is lost.
How WordPress picks a template
Block themes use the same hierarchy logic as classic themes, just with .html files in templates/ instead of .php files in the theme root. See our block theme vs. classic theme comparison if you are not sure which kind of theme you are actually running. WordPress walks from most specific to least specific and uses the first file that exists. The table covers the common views; the block theme template hierarchy reference lists every chain.
| Viewing | Checked in this order |
|---|---|
| A single post | single-post-{slug}.html → single-post.html → single.html → singular.html → index.html |
| A page | page-{slug}.html → page-{id}.html → page.html → singular.html → index.html |
| A category archive | category-{slug}.html → category-{id}.html → category.html → archive.html → index.html |
| A custom post type entry | single-{post_type}-{slug}.html → single-{post_type}.html → single.html → singular.html → index.html |
| A custom post type archive | archive-{post_type}.html → archive.html → index.html |
| The 404 page | 404.html → index.html |
Two things override this entirely. First, the database record described above. Second, a template assigned directly to a post or page: open the post editor, look for the Template panel in the sidebar, and check whether something specific is selected there. An explicit assignment beats the hierarchy every time, and it is invisible unless you go looking for it.
Plugins can add templates too. Since WordPress 6.7, register_block_template() lets a plugin supply a template under a slug. Core uses the plugin’s version only when the active theme has no file with that slug, and a saved copy in the database beats both (read from the WordPress 7.1.4 source, not run). So if a plugin’s template seems to ignore your theme, check whether your theme has a file with the same slug, and check the options menu for Reset.
Slug-based templates break quietly. page-about.html matches only while the page’s slug is about. Change the page’s slug to about-us and the template stops applying with no warning and no error. Changing only the title of a published page does not do this: WordPress keeps the stored slug when a post is updated and builds a slug from the title only when the slug is empty (read from the WordPress 7.1.4 source of wp_update_post() and wp_insert_post(), not run).
Template versus template part
A template renders an entire view and is selected by the hierarchy. A template part is a fragment, such as a header, footer or sidebar, that templates pull in. Parts live in parts/, templates live in templates/, and they are stored separately in the database as wp_template_part records.
The common confusion: you edit the header, and the change shows up on pages you did not intend to touch. That is correct behaviour. One part is shared by every template that includes it. If you want a different header on one template, you need a second part file and a template that references it. Editing the shared one will never give you per-template variation.
The reverse also happens. You put a full page layout into parts/ and wonder why the hierarchy never picks it up. Parts are not candidates in the hierarchy at all; nothing will ever route to them directly.
File naming and location
Check these before assuming anything more exotic:
- The folder is
templates/, plural, at the theme root, nottemplate/.block-templates/was the name during the Gutenberg-plugin era, and current WordPress still reads it. But if ablock-templates/orblock-template-parts/folder exists at all, WordPress loads templates and parts from that old pair and skipstemplates/andparts/(read from the WordPress 7.1.4 source, not run). A leftover old folder can hide every file you edit. - Template parts go in
parts/, nottemplate-parts/(which is the classic-theme convention for PHP partials). - The extension is
.html. A.phpfile intemplates/is ignored. - A PHP template left in the theme root can still win. If
single-post.phpsits next totemplates/single.html, posts get the PHP file. When WordPress finds a PHP template, it only considers block templates at least as specific as that file, sosingle.htmlis never a candidate (read from the WordPress 7.1.4 source, not run). Delete or rename the leftover PHP file. - Filenames are lowercase and use hyphens. WordPress compares each filename with the slugs it is looking for as an exact, case-sensitive string, so
single-Post.htmlorsingle_post.htmlnever matches, on any operating system (read from the WordPress 7.1.4 source, not run). templates/index.html(or the olderblock-templates/index.html) must exist. Without it, WordPress does not classify the theme as a block theme and the Site Editor does not appear.- If you are working in a child theme, its templates take priority over the parent’s. A leftover file in the child theme will quietly beat the parent file you are editing. Child themes have a stylesheet version of the same trap, which is why child theme CSS not loading is such a common companion problem.
A custom template does not need a theme.json entry to be selectable. Any file in templates/ whose name is not one of core’s default template types (such as single, page, archive or 404) shows in the post editor’s Template panel for every public post type, titled with its file name minus .html. A customTemplates entry adds a readable title and limits the post types that offer the template, and an entry with no postTypes limits it to pages (all read from the WordPress 7.1.4 source, not run). So if a custom template is missing from the panel on one post type, check its postTypes list. Our theme.json settings and styles guide covers the rest of that file. The theme.json generator builds the settings and styles part (palette, font sizes, layout widths), but not customTemplates, so add that array by hand:
{
"customTemplates": [
{ "name": "page-wide", "title": "Wide Page", "postTypes": ["page"] }
]
}
Caching: check it last
Caching is real but it is the least likely cause, and reaching for it first is how people lose an afternoon.
Purge your page cache and, if you run a persistent object cache such as Redis or Memcached, flush that too, since stale query results can be held there. Then reload with the browser cache bypassed.
What will not help: clearing OPcache. Block templates are .html files and are never compiled by PHP, so OPcache has nothing to do with them. If flushing OPcache appeared to fix this for you once, something else changed at the same time.
Still stuck?
With no database record, a correct filename, no explicit template assignment on the post, and caches already purged, look at plugins. Anything that filters template resolution, such as a page builder, a membership plugin, a multilingual plugin or an LMS, can substitute its own template late in the request. Switch to a default block theme and test with plugins disabled, then re-enable one at a time.
And if the template is applying but renders empty, that is a different problem: check that the block markup in the file is valid.
Sources
- WordPress Theme Handbook: Templates, Template Hierarchy, Custom Templates, Global Settings and Styles (theme.json)
- WordPress Developer Resources: register_block_template()
- WP-CLI Handbook: wp post list, wp post delete
William Lopez is the founder of Odie Themes. He builds the free WordPress tools and themes on this site and has been on WordPress.org since December 2019.
FAQ
Questions
Why is my block template not applying in WordPress?
Usually because a saved copy in the database is overriding the file. The moment you edit a template in the Site Editor and hit Save, WordPress creates a wp_template post record and serves that instead of the .html file in your theme folder. Every file edit after that point is invisible on the front end.
How do I make WordPress use my theme file instead of the Site Editor version?
Open Appearance then Editor then Templates, find the template, and choose Reset in its options menu. That deletes the database record and hands control back to the file on disk. If the menu offers Delete instead, the template exists only in the database and has no file behind it. If it offers neither, nothing in the database is overriding the file.
Where do block template files go in a WordPress theme?
Full templates go in a templates folder at the root of the theme, and reusable sections go in a parts folder. Both use the .html extension, lowercase filenames, and hyphens rather than underscores. A block theme also needs templates/index.html, or the older block-templates/index.html, or WordPress will not treat the theme as a block theme at all.
What is the difference between a template and a template part?
A template renders a whole page and is chosen by the template hierarchy based on what is being viewed. A template part is a fragment such as a header or footer that a template pulls in. Editing a header part changes every template that includes it, which is why part edits often look like they applied to the wrong place.
Does caching cause block templates not to update?
Sometimes, but it is the least likely cause and should be checked last. Page caches and persistent object caches can hold stale markup or query results, so purge both before drawing conclusions. Clearing OPcache does nothing here, because block templates are .html files and are never compiled by PHP in the first place.
Why did my page-slug template stop working?
Slug-based templates are matched against the current post slug at request time. Changing a page's slug (not its title) breaks the match: page-about.html silently stops applying once the slug becomes about-us. A new title alone keeps a published page's old slug. The same applies to category and tag templates. Either rename the file to match the new slug or assign the template explicitly in the post editor sidebar.