What It Means & How to Fix It in UE5
🧠 Why You’re Seeing This Error
This error means Unreal Engine detected a loop in the module dependency graph — basically, Module A depends on Module B, and Module B also depends on Module A (either directly or through other modules). This creates a circular dependency, which Unreal can’t resolve during compilation or linking.
It usually happens when:
- Two modules list each other in their
PublicDependencyModuleNames - A module calls into another, but that other module is already dependent on it
- You added a dependency to solve one error, but unknowingly introduced a loop
💥 Example Error Message
UnrealBuildTool: ERROR: Circular dependency detected between modules: MyGame -> MyFramework -> MyGame
🛠️ What Usually Causes This
❌ Mutual Dependencies in .Build.cs
// MyGame.Build.cs
PublicDependencyModuleNames.Add("MyFramework");
// MyFramework.Build.cs
PublicDependencyModuleNames.Add("MyGame"); // ❌ Circular reference
❌ Engine or Plugin Modules Referring to Each Other
This also happens in large codebases where multiple plugins or systems start referencing each other to expose functionality — especially with shared utilities, UI, or core logic.
❌ Including Public Headers from a Module That Also Depends on You
// MyFramework includes MyGame header
#include "MyGame/MyPlayerController.h" // ❌ Bad if both depend on each other
✅ How to Fix It – Step-by-Step
✔️ 1. Remove One Side of the Dependency
Most circular dependencies are not actually needed on both sides.
// MyFramework might not need MyGame:
PrivateDependencyModuleNames.Remove("MyGame"); // ✅ or move logic into another helper module
✔️ 2. Use PrivateDependencyModuleNames if You Only Need Internal Access
If one module only needs to call into another, and doesn’t need public access, switch from Public to Private:
// ✅ Better
PrivateDependencyModuleNames.Add("MyFramework");
This keeps the dependency hidden from other modules.
✔️ 3. Extract Shared Code to a Neutral Module
If both modules truly need shared logic, create a new module for the shared code:
// SharedUtilities.Build.cs
PublicDependencyModuleNames.Add("Core");
Modules that depend on it:
- MyGame
- MyFramework
✔️ 4. Double-Check Header Access
Avoid this:
// In a public header of MyFramework
#include "MyGame/MyActor.h" // ❌ pulls in full module dependency
Instead, forward declare:
class AMyActor; // ✅ No dependency created
✅ Summary: How to Fix “Circular Dependency Detected Between Modules” in UE5
| Cause | Fix |
|---|---|
| Both modules depend on each other | Remove or refactor to break the loop |
| Public dependency used unnecessarily | Switch to PrivateDependencyModuleNames |
| Shared logic causing back-and-forth | Move to a new shared or core module |
| Header access introduces indirect loop | Use forward declarations instead of includes |
