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/@RunAfterrelationships 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/@RunAfterrules. - 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
- DependencyCycle – Represents a detected circular dependency.
- NoOpDependencyCycle – Sentinel cycle implementation.
- RuntimeException – Base type for framework runtime errors.
- Inheritance
-
- Object
- Error
- RuntimeException
- CircularDependencyException
- 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