Skip to content
Themes

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.

Published Updated

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 isREST API source and has_theme_fileOptions menu offers
A theme file nobody has saved overtheme, trueNeither Reset nor Delete
A theme file with a saved copy in the databasecustom, trueReset, which deletes the saved copy
A template created in the Site Editor, with no filecustom, falseDelete
A plugin-registered template with a saved copycustomReset

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.

WordPress Site Editor Templates list with the options menu of the Single Posts template open, showing Edit and Reset
WordPress 7.1.4 in WordPress Playground, after we saved a test change to the Single Posts template through the REST API. Its menu offered Edit and Reset.

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):

StepActionResult
1Read the page template, never editedsource theme, has_theme_file true, no database post (wp_id 0)
2Saved a change to the single template, as the Site Editor’s Save doessource custom, has_theme_file true, a new wp_template post (wp_id 5)
3Created a new template, odie-landing, with no filesource custom, has_theme_file false
4Sent DELETE for both, without force, which moves a saved template to the trashsingle 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.

ViewingChecked in this order
A single postsingle-post-{slug}.html → single-post.html → single.html → singular.html → index.html
A pagepage-{slug}.html → page-{id}.html → page.html → singular.html → index.html
A category archivecategory-{slug}.html → category-{id}.html → category.html → archive.html → index.html
A custom post type entrysingle-{post_type}-{slug}.html → single-{post_type}.html → single.html → singular.html → index.html
A custom post type archivearchive-{post_type}.html → archive.html → index.html
The 404 page404.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, not template/. block-templates/ was the name during the Gutenberg-plugin era, and current WordPress still reads it. But if a block-templates/ or block-template-parts/ folder exists at all, WordPress loads templates and parts from that old pair and skips templates/ and parts/ (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/, not template-parts/ (which is the classic-theme convention for PHP partials).
  • The extension is .html. A .php file in templates/ is ignored.
  • A PHP template left in the theme root can still win. If single-post.php sits next to templates/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, so single.html is 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.html or single_post.html never matches, on any operating system (read from the WordPress 7.1.4 source, not run).
  • templates/index.html (or the older block-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

William Lopez

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.

WordPress.org About

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.