Skip to content

feat(schema-object-factory): include class name chain in circular dependency errors#3865

Merged
kamilmysliwiec merged 1 commit intonestjs:masterfrom
yogeshwaran-c:feat/improve-circular-dep-error
Apr 21, 2026
Merged

feat(schema-object-factory): include class name chain in circular dependency errors#3865
kamilmysliwiec merged 1 commit intonestjs:masterfrom
yogeshwaran-c:feat/improve-circular-dep-error

Conversation

@yogeshwaran-c
Copy link
Copy Markdown
Contributor

What kind of change does this PR introduce?

Feature / DX improvement in SchemaObjectFactory.

What is the current behavior?

When a circular dependency is detected during Swagger schema generation, the error message only identifies the property key involved:

Error: A circular dependency has been detected (property key: "someKey"). Please, make sure that each side of a bidirectional relationships are using lazy resolvers ("type: () => ClassType").

In a large codebase (e.g. a monorepo with hundreds of DTOs), knowing only the property name is often not enough to locate the offending class — developers end up commenting code out or running a binary search to identify the cycle.

Closes #3655

What is the new behavior?

extractPropertiesFromType now wraps the per-property extraction in a try/catch that prepends the currently-processed class name to the error message and re-throws. As the recursion unwinds, the error accumulates the full chain of classes that led to the failure:

Error: [RootResponseDto] [ParentEntity] [ChildEntity] A circular dependency has been detected (property key: "someProperty"). To resolve this, use a lazy resolver for the property type ("type: () => ClassType") on each side of the relationship, or break the cycle by introducing a reference via @ApiExtraModels.

The base error hint was also extended to mention @ApiExtraModels alongside lazy resolvers, since either approach can break a cycle.

This is a non-breaking change: existing error handling that already catches this error will continue to work, and the only user-visible difference is a more informative message.

Additional context

  • The implementation follows the approach suggested in the issue by the original reporter.
  • A regression test was added in test/services/schema-object-factory.spec.ts that simulates a circular dependency across two DTOs and asserts that both class names appear in the thrown error message.
  • The guard if (!err.message.startsWith(prefix)) avoids double-prefixing when the same class happens to appear twice consecutively in the chain (defensive — unlikely in practice).

…endency errors

When a circular dependency is detected during schema generation, the error
message now includes the chain of class names that led to the failure
(e.g. "[RootDto] [ParentDto] [ChildDto] A circular dependency has been
detected ..."). This is done by wrapping property extraction in
extractPropertiesFromType with a try/catch that prepends the current
class name — the chain builds up as the recursion unwinds.

Also expanded the base error hint to mention @ApiExtraModels as an
alternative resolution in addition to lazy resolvers.

In large codebases with many DTOs, identifying the offending class from
only the property key was painful; the class name chain makes the source
of the cycle immediately obvious.

Fixes nestjs#3655
@kamilmysliwiec kamilmysliwiec merged commit e5717f5 into nestjs:master Apr 21, 2026
1 check passed
@kamilmysliwiec
Copy link
Copy Markdown
Member

lgtm

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve error message for circular dependencies in SchemaObjectFactory

2 participants