Why a required Drupal media field is null in a Next.js front end
A required entity reference field in Drupal only guarantees that an editor picked something when they saved the form. It does not guarantee that the referenced entity is readable when a decoupled front end asks for it. If the referenced media is unpublished, deleted, or hidden from the current user, Drupal's GraphQL APIs resolve the reference to null, and a Next.js component that trusts the field will throw. Type those fields as nullable and render each item so that one missing reference can't fail the whole page.
How one unpublished image took a page down
On a decoupled Drupal site with a Next.js front end, a video gallery paragraph held a list of videos, each with a thumbnail image. The thumbnail was a required media reference field, so every gallery item had one when it was saved. Then an editor unpublished one of those image media entities. Nothing changed in the editing experience, and the gallery still looked complete in the Drupal admin.
For anonymous visitors, the page started returning a 500. The GraphQL response for that paragraph now had null where the thumbnail used to be, the renderer read a property off it, and the exception surfaced as a server error for the entire route, not just the broken gallery item.
Why the required field arrived as null
The confusing part is that every layer was behaving correctly on its own terms.
- Drupal's required flag is enforced when the entity is validated, which in practice means when someone saves the form. It says nothing about what happens to the target afterwards.
- Entity access runs when the reference is resolved for a response. An anonymous user can't view an unpublished media entity, so the API must not return it. Returning null is the safe answer.
- Deleted targets behave the same way. Drupal doesn't cascade a media delete into every field that pointed at it, so the reference can outlive its target and resolve to nothing.
So the field is "required" at write time and "optional" at read time, and the front end is only ever reading. If your GraphQL types are generated from a schema that marks the field non-null because it is required in Drupal, the types are lying to you. The same thing shows up in Drupal's JSON:API, where inaccessible related resources are left out of the response rather than included.
Preview makes this harder to catch. Editors and developers usually look at pages while logged in, often with permission to see unpublished content, so the reference resolves for them and the page renders. The failure only appears for the anonymous visitor.
What the fix looked like
We fixed it in two layers, because either one alone leaves a gap.
Stop claiming the field is always there
In Drupal, the thumbnail field was made optional in config. Keeping it required gave editors a nudge, but it also encouraged everyone downstream, including generated types, to assume a value that was never guaranteed. Being honest about the data model is better than a form rule that reads like a promise.
Render each item defensively
In the Next.js renderer, the gallery now treats both the thumbnail and the video as possibly missing. An item without a video is skipped, because there is nothing to play. An item without a thumbnail still renders, with no poster image. A minimal version of the pattern:
type MediaImage = { url: string; alt: string | null } | null;
type GalleryItem = {
id: string;
video: { url: string } | null;
thumbnail: MediaImage;
};
export function VideoGallery({ items }: { items: (GalleryItem | null)[] }) {
const playable = items.filter(
(item): item is GalleryItem => Boolean(item?.video?.url),
);
if (playable.length === 0) return null;
return (
<ul>
{playable.map((item) => (
<li key={item.id}>
<video
controls
preload="none"
src={item.video!.url}
poster={item.thumbnail?.url ?? undefined}
/>
</li>
))}
</ul>
);
}
The important choices are small. The list itself may contain nulls. Every reference is typed as nullable. The filter decides per item what "unusable" means, and the component returns nothing rather than an empty wrapper when no item survives. None of this needs a try/catch, and none of it hides real errors: a malformed response still fails loudly, but a legitimately missing reference doesn't.
Where else this bites in decoupled Drupal
Once you see the pattern it is everywhere. Any entity reference can come back null for the current viewer: media, linked content, taxonomy terms with access control, users. Paragraphs and blocks that build a page from many references are the riskiest, because one null deep in the tree can take down a route that is otherwise fine.
A few habits help:
- Generate GraphQL types with references nullable, even where Drupal marks the field required, and let TypeScript force the null checks.
- Test pages as an anonymous user against content that references unpublished and deleted entities, not only while logged in.
- Put an error boundary, or the equivalent per-section try/catch in server rendering, around page sections built from references, so a bug in one section degrades that section instead of returning a 500.
I like this fix because it moves the guarantee to where it can actually be kept. Drupal can't promise a reference will be readable later, but the renderer can promise it will behave sensibly when it isn't.
Key takeaways
- A required entity reference field in Drupal is checked when the entity is saved, not when a front end reads it.
- Unpublished, deleted or access-restricted targets resolve to null in decoupled responses, so references should be typed as nullable.
- Logged-in previews often hide the problem, so test pages as an anonymous visitor.
- Render lists of referenced items per item, skipping or degrading the broken ones, so one bad reference can't fail the page.