CircularDependencyException class

Thrown when a circular dependency is detected within the framework's dependency graph, interceptor ordering, or initialization process.

This exception indicates that one or more components depend on each other in a way that prevents resolution.

Circular dependencies may occur in several forms, including:

  • Interceptors that declare conflicting @RunBefore / @RunAfter relationships forming a cycle.
  • Dependency-injected services or pods that recursively depend on one another through constructors, factories, or providers.

Dependency Cycle

The cycle field contains a DependencyCycle describing the detected circular reference.

The cycle represents a closed dependency path in which resolution cannot proceed. If detailed cycle information is unavailable, a NoOpDependencyCycle is used as a safe default.

Implementations of DependencyCycle are framework-specific and may represent:

  • Ordered class or type paths (e.g. A → B → C → A)
  • Interceptor ordering chains
  • Module or plugin initialization loops

Example

// A depends on B, and B depends on A
class A {
  A(B b);
}

class B {
  B(A a);
}

// During dependency graph resolution:
throw CircularDependencyException(
  'Circular dependency detected while resolving services',
  cycle: TypeDependencyCycle([A, B, A]),
);

Typical Scenarios

  • Interceptor or handler chains with circular @RunBefore / @RunAfter rules.
  • Object graph creation in IoC containers or module initializers.
  • Misconfigured plugin or module registration that references itself directly or indirectly.

Debugging Tips

  • Inspect the cycle to identify the exact dependency path involved.
  • Review stack traces for the last successfully resolved component.
  • Check for circular annotation relationships in @RunBefore / @RunAfter.
  • Use dependency graph visualizations or diagnostic logs to locate cycles.

Design Notes

  • Extends RuntimeException, representing an unrecoverable framework-level configuration or initialization error.
  • Stores the detected dependency cycle as structured data rather than relying solely on error messages.
  • Uses NoOpDependencyCycle when cycle details are unavailable.
  • Should not be caught in user-space unless implementing custom dependency resolution, interceptor ordering, or plugin registration logic.
  • Typically thrown by dependency resolvers or interceptor ordering engines during application startup.

See Also

Inheritance
Available extensions

Constructors

CircularDependencyException(String message, {Object? cause, StackTrace? stackTrace, DependencyCycle? cycle})
Thrown when a circular dependency is detected within the framework's dependency graph, interceptor ordering, or initialization process.

Properties

cause → Object?
The underlying cause of this exception, if any.
finalinherited
cycle → DependencyCycle
The detected circular dependency path.
final
hashCode → int
The hash code for this object.
no setterinherited
message → String
The message describing the error.
finalinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
stackTrace → StackTrace
The associated stack trace.
finalinherited

Methods

getCause() → Object
The cause of this exception, if any.
inherited
getMessage() → String
The message associated with this exception.
inherited
getStackTrace() → StackTrace
The stack trace associated with this exception.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
printStackTrace([bool useErrorPrint = false]) → void

Available on Error, provided by the ErrorExtensions extension

Prints the error along with its stack trace.
printStackTrace([StackTrace? stacktrace, bool useErrorPrint = false]) → void

Available on Exception, provided by the ExceptionExtensions extension

Prints the exception and optional StackTrace if available.
printStackTrace([bool useErrorPrint = false]) → void

Available on RuntimeException, provided by the RuntimeExceptionExtensions extension

Extension on RuntimeException to support pretty stack trace printing.
printStackTrace([bool useErrorPrint = false]) → void

Available on Throwable, provided by the ThrowableExtensions extension

Extension on Throwable to support printing stack traces in a unified way.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited