A new block pattern renders as nothing. No error, no warning, no failed request \u2014 just empty space where your header used to be. Then, half an hour later, it works.<\/p>\n\n\n\n
I spent the first twenty minutes of a working day convinced I had broken four websites at once.<\/p>\n\n\n\n
The task was ordinary. I was making the strings in four themes translatable, and the standard way to do that is the way Twenty Twenty-Five does it: a template part that contains user-visible text becomes a one-line reference to a PHP pattern, because \u2026with the real markup moved into Then I loaded the site and there was no header. No footer either. Not a broken header \u2014 no header<\/em>. The page began at the first content section and ended at the last one.<\/p>\n\n\n\n No PHP error. No entry in the log. And it was happening on all four sites, which ruled out my usual suspicion that I had mistyped something.<\/p>\n\n\n\n The first half of the answer is eleven lines into An unrecognized slug renders as an empty string.<\/p>\n\n\n\n That is the whole failure mode. A pattern slug WordPress does not recognize produces an empty string<\/strong>. Not a warning, not a placeholder, not an HTML comment you could find in view-source. From the browser’s point of view the block was never in the template.<\/p>\n\n\n\n Which turns the question into a much better one: why was a pattern file that was plainly there<\/em> not registered?<\/p>\n\n\n\n It does not scan The guard clause is the interesting line.<\/p>\n\n\n\n Read that condition again. The cache is considered valid when the stored version matches Not the files’ modification times. Not a hash of the directory. Not the number of files in it. A string you type by hand.<\/p>\n\n\n\n And it is stored with a deliberate lifetime:<\/p>\n\n\n\n Thirty minutes.<\/p>\n\n\n\n So here is what actually happened to me. WordPress had scanned The stamp still matched. The cache was still valid. My new file was not in the list, so the pattern was never registered, so the reference to it rendered as an empty string.<\/p>\n\n\n\n For up to thirty minutes. Which is exactly why it appeared to heal itself while I was still trying to work out how to reproduce it.<\/p>\n\n\n\n Here is the part I find genuinely interesting, and the reason this is so disorienting when you hit it.<\/p>\n\n\n\n Deleting<\/strong> a pattern file behaves completely differently:<\/p>\n\n\n\n A missing file is noticed, announced, and self-healed.<\/p>\n\n\n\n Remove a pattern file and WordPress walks its cached list, finds the file gone, tells you about it, and throws the cache away. The system corrects itself and complains while doing it.<\/p>\n\n\n\n There is no equivalent path for a file you add.<\/strong> Nothing is looking for one. Nothing could be, without the directory scan the cache exists to avoid.<\/p>\n\n\n\n A deletion announces itself. An addition sits in the dark until the timer runs out.<\/p>\n\n\n\n So in That makes the whole class of problem disappear while you are building. It is the single most useful line in a block-theme developer’s config, and I now put it in every local install before I write anything.<\/p>\n\n\n\n Local only.<\/strong> This turns off a cache that exists for good reasons. It has no place on a production site, and no place on a site you have handed to someone else.<\/p>\n\n\n\n This is the part that matters if other people install your theme, and it is why I am writing it down.<\/p>\n\n\n\n Picture a release that adds one pattern file. Your customer uploads the new folder over the old one \u2014 no error, files land, everything looks fine. But if If that pattern happens to be their header, their site loses its header for half an hour, and the only person they can ask is you.<\/p>\n\n\n\n “Bump the version on every release” is advice you have read a hundred times and probably think of as bookkeeping \u2014 semantic versioning, changelogs, tidiness. It is not bookkeeping. In a block theme it is a cache-invalidation key<\/strong>, and skipping it has a specific, silent, user-visible failure attached.<\/p>\n\n\n\n It is also worth knowing which way round the rule runs. You do not bump the version because<\/em> you added a pattern. You bump it because you are releasing \u2014 and the pattern cache is one of several things quietly relying on you to do so.<\/p>\n\n\n\n A new block pattern renders as nothing. No error, no warning, no failed request \u2014 just empty space where your header used to be. Then, half an hour later, it works.<\/p>\n I spent the first twenty minutes of a working day convinced I had broken four websites at once.<\/p>","protected":false},"author":265843788,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1367,1414],"tags":[],"class_list":["post-1064","post","type-post","status-publish","format-standard","hentry","category-wordpress","category-block-themes"],"_links":{"self":[{"href":"https:\/\/timotheacreations.com\/fr\/wp-json\/wp\/v2\/posts\/1064","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/timotheacreations.com\/fr\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/timotheacreations.com\/fr\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/timotheacreations.com\/fr\/wp-json\/wp\/v2\/users\/265843788"}],"replies":[{"embeddable":true,"href":"https:\/\/timotheacreations.com\/fr\/wp-json\/wp\/v2\/comments?post=1064"}],"version-history":[{"count":2,"href":"https:\/\/timotheacreations.com\/fr\/wp-json\/wp\/v2\/posts\/1064\/revisions"}],"predecessor-version":[{"id":1066,"href":"https:\/\/timotheacreations.com\/fr\/wp-json\/wp\/v2\/posts\/1064\/revisions\/1066"}],"wp:attachment":[{"href":"https:\/\/timotheacreations.com\/fr\/wp-json\/wp\/v2\/media?parent=1064"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/timotheacreations.com\/fr\/wp-json\/wp\/v2\/categories?post=1064"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/timotheacreations.com\/fr\/wp-json\/wp\/v2\/tags?post=1064"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}.html<\/code> files are served verbatim and never execute PHP. So parts\/header.html<\/code> stopped being markup and became this:<\/p>\n\n\n\n<!-- wp:pattern {\"slug\":\"athena\/header\"} \/--><\/code><\/pre>\n\n\n\npatterns\/header.php<\/code>, where esc_html__()<\/code> works.<\/p>\n\n\n\nNothing was wrong, according to everything<\/h2>\n\n\n\n
WP_DEBUG<\/code> on: silence. The pattern file was sitting on disk exactly where the reference pointed, with balanced block comments and valid markup. View source showed no trace that a block had been there at all \u2014 not a comment, not an empty <div><\/code>. The header had simply never existed.<\/p>\n\n\n\nA failure with no error message is not a bug you debug. It is a behaviour you have not read about yet.<\/pre>\n\n\n\n
An unregistered pattern is not an error<\/h2>\n\n\n\n
render_block_core_pattern()<\/code>:<\/p>\n\n\n\n\/\/ wp-includes\/blocks\/pattern.php\nfunction render_block_core_pattern( $attributes ) {\n \/\/ \u2026\n $registry = WP_Block_Patterns_Registry::get_instance();\n\n if ( ! $registry->is_registered( $slug ) ) {\n return '';\n }<\/code><\/pre>\n\n\n\nWordPress caches the list of your pattern files<\/h2>\n\n\n\n
patterns\/<\/code> on every request. It scans once and remembers, in a site transient:<\/p>\n\n\n\n\/\/ wp-includes\/class-wp-theme.php\nprivate function get_pattern_cache() {\n \/\/ \u2026\n $pattern_data = get_site_transient( 'wp_theme_files_patterns-' . $this->cache_hash );\n\n if ( is_array( $pattern_data ) && $pattern_data['version'] === $this->get( 'Version' ) ) {\n return $pattern_data['patterns'];\n }\n return false;\n}<\/code><\/pre>\n\n\n\n$this->get( 'Version' )<\/code> \u2014 the version string in your style.css<\/code> header.<\/strong><\/p>\n\n\n\nprivate static $cache_expiration = 1800;<\/code><\/pre>\n\n\n\npatterns\/<\/code> at some point that morning, found the files that existed at that moment<\/em>, stored the list, and stamped it with the theme’s version. I then added patterns\/header.php<\/code> and did not touch Version<\/code>, because why would I \u2014 I was moving markup around, not making a release.<\/p>\n\n\n\nThe asymmetry that makes it feel like a haunting<\/h2>\n\n\n\n
\/\/ wp-includes\/block-patterns.php\nif ( ! file_exists( $file_path ) ) {\n _doing_it_wrong(\n __FUNCTION__,\n sprintf(\n __( 'Could not register file \"%s\" as a block pattern as the file does not exist.' ),\n $file\n ),\n '6.4.0'\n );\n $theme->delete_pattern_cache();\n continue;\n}<\/code><\/pre>\n\n\n\nWhile you are working: switch the cache off<\/h2>\n\n\n\n
get_block_patterns()<\/code> opens with an escape hatch:<\/p>\n\n\n\n$can_use_cached = ! wp_is_development_mode( 'theme' );<\/code><\/pre>\n\n\n\nwp-config.php<\/code> on your local site:<\/p>\n\n\n\ndefine( 'WP_DEVELOPMENT_MODE', 'theme' );<\/code><\/pre>\n\n\n\nWhen you ship: bump the version, every time<\/h2>\n\n\n\n
Version<\/code> in style.css<\/code> is unchanged, the cached list on their<\/em> server is still stamped valid. Their site keeps the old list. The new pattern is not registered. Anything referencing it renders as nothing.<\/p>\n\n\n\nEn bref<\/h2>\n\n\n\n
\n
Version<\/code>.<\/li>\n\n\n\ndefine( 'WP_DEVELOPMENT_MODE', 'theme' );<\/code><\/li>\n\n\n\nVersion<\/code> in style.css<\/code>, ou vos visiteurs voient l\u2019en-t\u00eate vide \u00e0 votre place.<\/li>\n<\/ul>\n\n\n\nI build a small family of WordPress block themes \u2014 Athena, Apollo, Hera and Hermes \u2014 and most of what I write here is something that cost me an afternoon first. Every release in the family bumps its version whether or not it feels like it deserves one, for exactly the reason above.<\/em><\/pre>","protected":false},"excerpt":{"rendered":"