
You configured caching, enabled Dynamic Page Cache, and yet pages for logged-in users are still slow. Looking at the headers, you find X-Drupal-Dynamic-Cache: UNCACHEABLE. The culprit is almost always the same: one small personalised element (“Hello Akram”, the cart counter, a “My account” link) that bubbled the user cache context all the way up to the whole page.
This article follows up on the Cache API article and explains how Drupal isolates those fragments with lazy builders and placeholders, and how to find out what is breaking your cache.
The problem: cacheability bubbling
In Drupal, every render array carries its cache metadata (#cache: contexts, tags, max-age). During rendering, that metadata bubbles up to the parents: if an element varies per user, its container varies per user too, and so on up to the response.
Take a perfectly ordinary hook_preprocess_page():
function my_theme_preprocess_page(array &$variables) {
$account = \Drupal::currentUser();
$variables['greeting'] = [
'#markup' => t('Hello @name', ['@name' => $account->getDisplayName()]),
'#cache' => ['contexts' => ['user']],
];
}
The metadata is correct, and that is exactly the problem: the user context bubbles up to the page. Dynamic Page Cache refuses to cache a response whose cacheability matches the auto-placeholdering conditions (more on that below), so the whole page becomes UNCACHEABLE because of one line of text.
The fix: defer the fragment
A lazy builder is a callback that builds a render array later, when Drupal replaces placeholders. Instead of handing over the content, you hand over the recipe:
$variables['greeting'] = [
'#lazy_builder' => ['my_module.user_greeting:build', []],
'#create_placeholder' => TRUE,
];
Drupal then caches the page with a placeholder where the fragment belongs, and runs the lazy builder on every request to fill the hole. The rest of the page is served from cache.
The service
# my_module.services.yml
services:
my_module.user_greeting:
class: Drupal\my_module\UserGreeting
arguments: ['@current_user']
<?php
namespace Drupal\my_module;
use Drupal\Core\Security\TrustedCallbackInterface;
use Drupal\Core\Session\AccountProxyInterface;
use Drupal\Core\StringTranslation\StringTranslationTrait;
final class UserGreeting implements TrustedCallbackInterface {
use StringTranslationTrait;
public function __construct(
private readonly AccountProxyInterface $currentUser,
) {}
public static function trustedCallbacks(): array {
return ['build'];
}
public function build(): array {
return [
'#markup' => $this->t('Hello @name', [
'@name' => $this->currentUser->getDisplayName(),
]),
'#cache' => [
'contexts' => ['user'],
'tags' => ['user:' . $this->currentUser->id()],
],
];
}
}
Rules to know
- Trusted callbacks: since Drupal 9, render callbacks must be declared trusted. In Drupal 10, a callback missing from
trustedCallbacks()throws an exception. ImplementTrustedCallbackInterfaceon the service class. - Scalar arguments only: the arguments array may only contain
string,int,float,boolorNULL. Pass an ID, never an entity:['my_module.cart:build', [$cart_id]]. These arguments are part of the placeholder key, so they must be serialisable and stable. - Allowed properties: an element with
#lazy_buildermay only carry “meta” properties (#cache,#create_placeholder,#weight…). A#markupor children next to the#lazy_builderare rejected by the renderer: everything must be built in the callback. - The callback does not see the page context: it only gets its arguments. Everything it needs must come from those arguments or from injected services.
Auto-placeholdering: placeholders without asking
You don’t always need #create_placeholder => TRUE. Drupal can decide on its own to placeholder a #lazy_builder element when its cacheability is “poor”. The thresholds live in services.yml:
parameters:
renderer.config:
auto_placeholder_conditions:
max-age: 0
contexts: ['session', 'user']
tags: []
An element with a max-age of 0, or a session or user context, is set aside automatically. Key point: the decision is made on the #cache declared on the lazy builder element itself, before the callback runs. If the contexts are only known inside the callback, Drupal cannot guess them:
// Auto-placeholdered: Drupal knows up front that the fragment varies per user.
$build['cart'] = [
'#lazy_builder' => ['my_module.cart:build', [$cart_id]],
'#cache' => ['contexts' => ['user']],
];
Dynamic Page Cache uses these same conditions to decide whether a response is cacheable. That is why a user context leaking up to the page makes it UNCACHEABLE.
Good news: blocks are already rendered through a lazy builder by
BlockViewBuilder. A block that declares its contexts correctly ingetCacheContexts()is placeholdered on its own. Leaks mostly come from preprocess functions, controllers and hand-written formatters.
Replacement strategies: SingleFlush and BigPipe
Once the page is cached, the placeholders still have to be replaced. Core ships two strategies:
| Strategy | How it works | When |
|---|---|---|
| SingleFlush | Placeholders are rendered server-side before the response is sent | By default, and for visitors without a session |
| BigPipe | The page is sent immediately, fragments are streamed afterwards | big_pipe module enabled and a user with a session |
BigPipe does not apply to anonymous visitors without a session: for them, Internal Page Cache serves the complete page with placeholders already replaced.
The anonymous trap: Internal Page Cache ignores max-age
Internal Page Cache (the page_cache module) caches the full response for anonymous users and ignores the max-age bubbled up by your render arrays. An anonymous block with max-age: 0 (weather, a stock counter) will be frozen for every visitor.
Two options:
// Option 1: exclude the page from the anonymous cache (keep this for truly dynamic pages).
\Drupal::service('page_cache_kill_switch')->trigger();
Option 2, cleaner: load the fragment client-side (a JSON route or #attached JavaScript) and keep the HTML page fully cacheable, including by a reverse proxy or a CDN.
Diagnosing: cacheability headers
Enable the debug headers in development.services.yml:
parameters:
http.response.debug_cacheability_headers: true
Then inspect the response with a logged-in user’s session cookie:
curl -sI https://example.com/node/1 -H "Cookie: SESS...=..." | grep -i x-drupal
X-Drupal-Dynamic-Cache: UNCACHEABLE
X-Drupal-Cache-Contexts: languages:language_interface route theme timezone url.path user user.permissions
X-Drupal-Cache-Tags: config:system.site node:1 node_view rendered user:12
X-Drupal-Cache-Max-Age: -1 (Permanent)
The user context in X-Drupal-Cache-Contexts explains the UNCACHEABLE. You still need to find who introduced it: disable blocks one by one, or search for 'contexts' => ['user'] and currentUser() calls in your preprocess functions and controllers. Once the fragment is converted to a lazy builder, you should see X-Drupal-Dynamic-Cache: HIT on the second load.
Checklist
- Anything that varies per user or per session goes through a
#lazy_builder(or a block). - Contexts are declared on the lazy builder element to allow auto-placeholdering, and on the callback’s result.
- Arguments are scalars (IDs, not objects).
- The service implements
TrustedCallbackInterface. - For anonymous users, don’t rely on
max-age: 0being honoured: use the kill switch or client-side loading. - Always verify with the
X-Drupal-*headers.
Conclusion
Most performance problems for logged-in users don’t come from a slow SQL query, but from one personalised fragment that poisons the cache of the whole page. Lazy builders let you keep 95% of the page cached and compute only what actually varies. It is one of the most powerful mechanisms in Drupal’s render system, and one of the least known.
