fix(core): Guard relation custom field resolution against a missing entity id

[brmk]

Description

Relation-type custom fields selected on an embedded value object with no database id — the canonical case being OrderAddress (Order.shippingAddress / billingAddress) — crash with:

The loader.load() function must be called with a value, but got: undefined.

This is a regression from #4923 (perf(core): resolve relation custom fields using request-scoped DataLoader batching): relation custom fields are now resolved through a DataLoader keyed by the parent entity id. For an OrderAddress that id is undefined (it is a JSON snapshot with no entity id), so DataLoader.load(undefined) throws. It surfaces as a GraphQL error (HTTP 200 with an errors array), so it is invisible in server logs and can silently break checkout flows that read the order's shipping/billing address. Before #4923 these relations resolved without DataLoader and returned null on an OrderAddress rather than throwing.

Fix

Guard the undefined entityId in CustomFieldRelationResolverService.resolveRelation and resolve to null (or [] for a list field) — an embedded value object legitimately has no id. ResolveRelationConfig.entityId is widened to ID | undefined to reflect what the single call site (generate-resolvers.ts, source[ENTITY_ID_KEY]) actually passes.

Reproduction

1. Define a relation custom field on Address (any target entity).
2. Shop API: create an active order, then setOrderShippingAddress with the custom field set.
3. Query activeOrder { shippingAddress { customFields { <relation> { id } } } } → GraphQL error.

Tests

Added an e2e regression test to custom-field-relations.e2e-spec.ts (Address entity group) that drives the order shipping-address path. Verified locally:

• With the fix: the custom-field-relations e2e suite passes (62/62).
• Without the fix: the new test fails with The loader.load() function must be called with a value, but got: undefined.

Fixes #5004

---

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
vendure-storybook	Ready	Preview, Comment	Jul 20, 2026 12:57pm

[vendure-ci-automation-bot]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f812a3d3-1b40-46bf-887c-19319f58b51f

📥 Commits

Reviewing files that changed from the base of the PR and between 30015e0 and 81b7a5e.

📒 Files selected for processing (2)

• packages/core/e2e/custom-field-relations.e2e-spec.ts
• packages/core/src/api/common/custom-field-relation-resolver.service.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/core/src/api/common/custom-field-relation-resolver.service.ts

---

📝 Walkthrough

Walkthrough

Custom field relation resolution now supports embedded value objects without an id. The resolver returns null for single relations and an empty array for list relations instead of invoking the DataLoader with an undefined identifier. An end-to-end test covers relational custom fields on an order’s shippingAddress.

Possibly related issues

• relation-type custom field on OrderAddress throws "loader.load() ... got: undefined" in v3.7 (DataLoader called with an undefined entity id) #5004 — Adds the null-identifier guard and regression coverage for id-less order address values.

Possibly related PRs

• vendurehq/vendure#4923 — Both changes modify CustomFieldRelationResolverService.resolveRelation() and its DataLoader handling.

Suggested reviewers: michaelbromley, supermadu7

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main fix for missing entity IDs in relation custom field resolution.
Description check	✅ Passed	The description covers the bug, fix, reproduction, and tests, with only optional template sections left unfilled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[brmk]

I have read the CLA Document and I hereby sign the CLA

[grolmus]

Thanks @brmk — clean, honest, well-scoped fix. Reviewed the diff, traced the root cause, and ran it locally.

Root cause confirmed: generate-resolvers.ts attaches [ENTITY_ID_KEY]: source.id to the custom-fields resolver value, and for an OrderAddress (an embedded value object with no id) that's undefined, which then reached loader.load(undefined). Guarding entityId == null and returning []/null is the right fix, in the right place:

• It sits after the eager-load short-circuit, so no id-bearing entity can wrongly hit the null branch.
• == null correctly matches only null/undefined (Vendure ids are never a falsy-but-valid 0).
• Returning null restores the documented pre-3.7 behaviour — the stored FK scalar (singleId) isn't consulted by either resolution path even today (the DataLoader path joins the parent entity table by id, which an embedded object doesn't have), so null is the honest result here rather than something being silently dropped.
• The type widening to ID | undefined is accurate and non-breaking (ResolveRelationConfig isn't part of the public API).

Testing: the new e2e reproduces the real crash path (set a shipping address with relation custom fields, then query them). Ran the full custom-field-relations suite locally — 62 passed.

Two optional, non-blocking follow-ups (no need to hold this PR):

1. A one-line assertion on customFields.primitive in the new test would confirm the guard doesn't collaterally affect scalar custom fields on the snapshot.
2. Actually resolving OrderAddress relation custom fields from the stored <name>Id scalar would be a nice future enhancement — it's a separate feature from this crash fix, so worth a follow-up issue if the team wants it.

Approving. 🚀