Errors when displaying Entity Reference field as a block in block layout

I've created a merge request with the suggested change in place.

I realized after submitting this that there is a new 3.1 release, so I tried installing that to see if it fixed my issue. It did not, but the patch applies to the new version and still works, but now I get a bunch of Warnings such as

Warning: Undefined array key "wrappers" in Drupal\custom_field\Plugin\Field\FieldFormatter\BaseFormatter->getFormattedValues() (line 477 of modules/contrib/custom_field/src/Plugin/Field/FieldFormatter/BaseFormatter.php).

and

Warning: Trying to access array offset on value of type null in template_preprocess_custom_field_item() (line 119 of modules/contrib/custom_field/custom_field.module).

so I've reverted to 3.0.x

Thank you for the patch and insight on the wrappers issue. The latter can probably be resolved with just saving the manage display settings as theres a new setting in there but I will resolve it anyway. I will try to get this reviewed and merged in the next day or 2. I know there are other similar deprecations for some of the other field plugins so i will want to take care of them all.

I'm unsure on this suggested fix. According to docs, renderInIsolation sounds like it should be used as a replacement for deprecated renderPlain(). In this case, it sounds like it could affect the #cache tags: https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Render%21...

The other issue is that renderInIsolation is was introduced in Drupal 10.3 so this wouldn't be backwards compatible. The suggested example for backward compatibility is here: https://www.drupal.org/node/3407994#comment-15540719 →

I'm no expert on layout builder nor caching as it can get a bit complex in these various scenarios but I just want to be careful to not break other things. I think lets keep the dialog open on this issue to help make a confident approach.

That all makes sense to me. I'm also not an expert on all the caching and context details here. I just know that when I tried to place the field as a block in block layout, I started getting the DWSOD. Given that this was happening with an Entity Reference field, I wonder if the core Entity Reference Field Formatter has an example we can learn from. Maybe the solution is to detect whether there is a render context, and only renderInIsolation or renderPlain when it isn't present. I appreciate you being responsive on this. It is a very cool module, that I became familiar with due to a talk at PNW Drupal Summit and then again a bit later at BADCamp last year.

Hello! Just here to confirm that we're seeing the wrapper/offset warnings described in #4 after updating to 3.1.0. Re-saving manage display settings didn't help.

I haven't had time to investigate further. We've reverted to 3.0.x for now.

Thanks for the confirm on wrappers. Subscribe to this bug and I'll get a patch up shortly to test out: https://www.drupal.org/project/custom_field/issues/3501250 🐛 Warning: Undefined array key "wrappers" Active

There's a patch now in that issue ^. Just saving manage display wouldn't have resolved it. You would need to actually edit the field settings form in manage display and then save. There's essentially a new fieldset in the field settings there that allows you to set html wrapper tags and classes to the rendered output. It's similar to the fences module but of course for these subfields.

We ran into this same issue again with a URL field type, so I've added a commit to apply the same fix to the URL formatter.

I ran this through Grok to get suggestions and explain the impact of the suggested change. It suggested instead using renderRoot(). I need verification that the following would work and test out in both cases for working in layout builder while preserving cache invalidation in other contexts.

Your concern is valid: the difference between render() and renderInIsolation() (or similar methods) in Drupal’s rendering system can indeed affect how caching behaves, especially when moving from a node context to a Layout Builder block context. Let’s analyze the issue, explain why the error occurs, assess the caching implications, and propose a solution that balances functionality and performance.
The Problem
Normal Node Context: Your formatValue() method works fine because nodes are typically rendered as part of a full page render pipeline, where the renderer (RendererInterface) can process the render array ($build) and integrate it into the page’s cacheable metadata (e.g., cache tags, contexts, etc.).

Layout Builder Block Context: When this field is rendered inside a block used in Layout Builder, the rendering process happens in a more isolated or nested context. Layout Builder often renders components individually, and the renderer may expect the output to be "isolated" (e.g., not relying on the full page’s render pipeline). The error suggesting renderInIsolation() likely stems from this isolation requirement—Drupal’s renderer might detect that $this->renderer->render($build) is being called in a way that doesn’t properly handle nested rendering or placeholder replacement.

render() vs. renderInIsolation()
render():
Processes the render array, applies #pre_render callbacks, resolves placeholders, and integrates cache metadata into the current render context.

Relies on being part of a broader render pipeline (e.g., a page or a parent element) to finalize output and caching.

If called in an isolated context (like Layout Builder’s block rendering), it might throw an error or fail to handle nested dependencies correctly.

renderInIsolation():
Renders the element in a standalone way, bypassing some of the broader render context dependencies (e.g., placeholders or late-stage processing).

Often used for AJAX responses, previews, or isolated components where the full page context isn’t available.

Can skip certain optimizations (like placeholder replacement), potentially impacting caching.

Caching Concerns
In Node Context: Using render() ensures that the cache metadata (e.g., #cache['tags'] from the entity) is bubbled up to the page level. This means the node’s rendered output is cached efficiently, and cache invalidation works as expected (e.g., when the referenced entity changes, its cache tags invalidate the node’s cache).

With renderInIsolation(): If you switch to renderInIsolation(), the rendered output might not fully participate in the page’s cache bubbling. This could:
Prevent cache tags from being merged into the parent context (e.g., the block or page), reducing cache invalidation granularity.

Force the element to be re-rendered more often (e.g., if it’s treated as uncacheable or cached separately).

Potentially bypass Drupal’s BigPipe or lazy loading optimizations.

Your concern about caching being “negatively impacted in the first scenario” (node context) if you switch to renderInIsolation() is spot-on—moving away from render() could disrupt the seamless cache integration that works well in the node case.
Suggested Solution
To fix the Layout Builder error while preserving caching behavior in both contexts (node and block), you should:
Use renderRoot() instead of renderInIsolation(): This method is designed for rendering standalone elements while still respecting cache metadata and bubbling it up to the parent context.

Ensure cache metadata is properly attached: Explicitly add cache contexts or max-age if needed, though your current #cache['tags'] should suffice for entity-based invalidation.

Test for isolation needs: If renderRoot() doesn’t resolve the error, consider conditionally isolating the render based on the context (though this should be a last resort).

I confirmed renderInIsolation with renderRoot, and confirmed that that works as well. So I've updated the merge request. I have not reviewed all the formatters to see if others need to be updated. I've only updated the items that we ran into under time pressure.

I had missed the alternate suggestion of renderRoot in the original error. I just now read up on the difference, and renderRoot seems the more appropriate choice here.

There are more formatters using this pattern, but I'm unsure if this change is needed with them. Apologies for not having more time to dig in.

renderRoot isn't working cause cache isn't getting invalidated so I moved the render call up the field BaseFormatter and it seems to be working fine with this revision both in layout builder and in normal entity context. Please test the revised patch and see if that works for you.

@ultrabob, Something to note here is that with renderRoot and I assume also renderInIsolation, the cache tags don't get invalidated so if you had changed the referenced entity's title for instance, you likely didn't see that change reflected on the parent entity. Now, with the changes, you should see proper behavior. I was able to reproduce a similar error you were receiving prior to the change which was happening on updating the block in layout builder. I don't ever use layout builder so didn't catch this problem. I do think the updated patch should resolve your issues though and encompasses all the formatters that were using the renderer method.

@apmspooner thanks for your prompt attention to this issue. Very much appreciated. Since you also bumped the module version on the MR, I had to do an upgrade of the module before I could test. I can't promise that issues I report are due to the original issue and not the new version of the module, though it seems that they are.

I first confirmed the issue you pointed out with caching. With my patch in place, If I updated the title of a referenced node, the title was not updated in the custom field display.

After upgrading the module, applying the new patch, running database updates, and clearing cache. Viewing a page with the field placed in block layout (note, not layout builder, I'm placing the field as a block). I get the following WSOD error:

The website encountered an unexpected error. Try again later.

LogicException: Render context is empty, because render() was called outside of a renderRoot() or renderInIsolation() call. Use renderInIsolation()/renderRoot() or #lazy_builder/#pre_render instead. in Drupal\Core\Render\Renderer->doRender() (line 303 of core/lib/Drupal/Core/Render/Renderer.php).
Drupal\Core\Render\Renderer->render(Array) (Line: 481)
Drupal\custom_field\Plugin\Field\FieldFormatter\BaseFormatter->getFormattedValues(Object, 'en') (Line: 35)
Drupal\custom_field\Plugin\Field\FieldFormatter\CustomFormatter->viewValue(Object, 'en') (Line: 353)
Drupal\custom_field\Plugin\Field\FieldFormatter\BaseFormatter->viewElements(Object, 'en') (Line: 91)
Drupal\Core\Field\FormatterBase->view(Object, 'en') (Line: 268)
Drupal\Core\Entity\Entity\EntityViewDisplay->buildMultiple(Array) (Line: 282)
Drupal\layout_builder\Entity\LayoutBuilderEntityViewDisplay->buildMultiple(Array) (Line: 226)
Drupal\Core\Entity\Entity\EntityViewDisplay->build(Object) (Line: 461)
Drupal\Core\Entity\EntityViewBuilder->viewField(Object, Array) (Line: 243)
Drupal\Core\Field\FieldItemList->view(Array) (Line: 174)
Drupal\ctools_block\Plugin\Block\EntityField->blockAccess(Object) (Line: 127)
Drupal\Core\Block\BlockBase->access(Object, 1) (Line: 124)
Drupal\block\BlockAccessControlHandler->checkAccess(Object, 'view', Object) (Line: 109)
Drupal\Core\Entity\EntityAccessControlHandler->access(Object, 'view', Object, 1) (Line: 329)
Drupal\Core\Entity\EntityBase->access('view', NULL, 1) (Line: 63)
Drupal\block\BlockRepository->getVisibleBlocksPerRegion(Array) (Line: 138)
Drupal\block\Plugin\DisplayVariant\BlockPageVariant->build() (Line: 270)
Drupal\Core\Render\MainContent\HtmlRenderer->prepare(Array, Object, Object) (Line: 128)
Drupal\Core\Render\MainContent\HtmlRenderer->renderResponse(Array, Object, Object) (Line: 90)
Drupal\Core\EventSubscriber\MainContentViewSubscriber->onViewRenderArray(Object, 'kernel.view', Object)
call_user_func(Array, Object, 'kernel.view', Object) (Line: 111)
Drupal\Component\EventDispatcher\ContainerAwareEventDispatcher->dispatch(Object, 'kernel.view') (Line: 186)
Symfony\Component\HttpKernel\HttpKernel->handleRaw(Object, 1) (Line: 76)
Symfony\Component\HttpKernel\HttpKernel->handle(Object, 1, 1) (Line: 53)
Drupal\Core\StackMiddleware\Session->handle(Object, 1, 1) (Line: 48)
Drupal\Core\StackMiddleware\KernelPreHandle->handle(Object, 1, 1) (Line: 28)
Drupal\Core\StackMiddleware\ContentLength->handle(Object, 1, 1) (Line: 32)
Drupal\big_pipe\StackMiddleware\ContentLength->handle(Object, 1, 1) (Line: 116)
Drupal\page_cache\StackMiddleware\PageCache->pass(Object, 1, 1) (Line: 90)
Drupal\page_cache\StackMiddleware\PageCache->handle(Object, 1, 1) (Line: 48)
Drupal\Core\StackMiddleware\ReverseProxyMiddleware->handle(Object, 1, 1) (Line: 51)
Drupal\Core\StackMiddleware\NegotiationMiddleware->handle(Object, 1, 1) (Line: 36)
Drupal\Core\StackMiddleware\AjaxPageState->handle(Object, 1, 1) (Line: 51)
Drupal\Core\StackMiddleware\StackedHttpKernel->handle(Object, 1, 1) (Line: 741)
Drupal\Core\DrupalKernel->handle(Object) (Line: 19)

The formatting here was confusing, but I've tracked it back to line 481 of src/Plugin/Field/FieldFormatter/BaseFormatter.php

$rendered_value = $this->renderer->render($value);

Changing that line to be

$rendered_value = $this->renderer->renderRoot($value);

appears to get rid of the error, and also in some brief testing seems not to exhibit the caching issue you pointed out.

I also just tested placing the block in a block layout (theme region) and not using layout builder. I have no issues with rendering as is with the patch. Not getting those errors and not having to convert to renderRoot. What version of Drupal core are you on? I'm on 10.4.3 locally. I can only assume you must have something considerably different going on than me with your configuration and I don't know of anyone else having this issue. I was previously getting similar errors when in layout builder but just moving the render up to the base formatter of the field resolved that. I assume also this is just a custom field directly on the block right? No paragraphs or other weirdness in the mix?

I can't merge this with renderRoot solution. The cache doesn't get invalidated. Clone your custom field to a node type and you'll see that a referenced entity when changed does not change the rendered result on the custom field. I'm gonna push a new release but will have to leave this on hold for now as I just can't reproduce the issue and I don't feel comfortable with the caching issue resulting from swapping out renderRoot for render.

Thanks. I'm on Drupal 10.4.1 locally. The field is not in a paragraph or anything like that. It is in a field group on the form.

I want to get this answer to you quickly, but after that I'll dig in and try to identify exactly which field on what content type is giving me those errors so I can provide more detail.

To be sure that it wasn't a core version I updated my local to 10.4.3 and can still reproduce the error. I have the same field attached to three content types and the field placed as a block in layout builder. I have attached the field storage config, and the config for the field on the landing page content type which is the content type I'm trying to view when I get an error. I only get the error if the page I'm trying to view has content in the field. I've also attached the block config, just to try and make sure you can see what I'm doing here.

This now works good with ctools blocks, layout builder, etc... so merging and calling it Fixed!