Bug / UX Enhancement - Circular Dependency Error Messages

[asadjan4611]

Bug Description

When webpack encounters a circular dependency, the error message is too generic and doesn't provide enough information to help developers debug the issue. The current error only states "There is a circular build dependency" without showing:

• Which modules are involved in the cycle
• The dependency chain showing how modules depend on each other
• File paths and line numbers where dependencies are imported
• Suggestions on how to break the cycle

This makes debugging circular dependencies extremely difficult, especially in large codebases with hundreds of modules.

Current error message:

There is a circular build dependency, which makes it impossible to create this module

Problem: Developers have no idea which files are causing the circular dependency and must manually trace through imports, which can take hours in large projects.

2. Link to Minimal Reproduction and Steps to Reproduce

Minimal Reproduction Repository

Create a simple project with the following structure:

File structure:

project/
├── src/
│   ├── index.js
│   ├── moduleA.js
│   └── moduleB.js
└── webpack.config.js

src/index.js:

import { funcA } from './moduleA';
console.log('App started');

src/moduleA.js:

import { funcB } from './moduleB';

export function funcA() {
  return 'Function A';
}

src/moduleB.js:

import { funcA } from './moduleA';

export function funcB() {
  return 'Function B';
}

webpack.config.js:

module.exports = {
  mode: 'development',
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: __dirname + '/dist'
  }
};

Link to Minimal Reproduction and step to reproduce

1. Create the files above in a new directory
2. Run npm init -y to initialize package.json
3. Install webpack: npm install --save-dev webpack
4. Run webpack: npx webpack
5. Observe the error message

Expected result: Error message shows circular dependency chain
Actual result: Generic error message without dependency chain

Alternative: Large Project Scenario

If testing in a large project (1000+ modules):

1. Create a circular dependency between any two modules
2. Run webpack build
3. Observe the generic error message
4. Try to find the circular dependency manually (very time-consuming)

Project structure example:

Large project with:
- 500+ source files
- Multiple entry points
- Complex dependency graph
- Circular dependency somewhere in the chain

Expected Behavior

The error message should display:

1. Full dependency chain showing the circular path

   • Example: moduleA.js → moduleB.js → moduleA.js

2. File paths with line numbers for each dependency

   • Show where each import occurs

3. Visual representation of the cycle

   • Clear indication of the circular path

4. Actionable suggestions for breaking the cycle

   • Common solutions like extracting shared code
   • Using dynamic imports
   • Refactoring suggestions

Expected error output:

ERROR in Circular dependency detected

Circular dependency chain:
  ./src/moduleA.js (line 1)
    → ./src/moduleB.js (line 1)
      → ./src/moduleA.js (line 1)

To fix this circular dependency:
  - Extract shared code from moduleA.js and moduleB.js to a separate module
  - Use dynamic imports: import('./moduleB').then(...)
  - Consider refactoring the module structure to remove the dependency cycle

Actual Behavior

Current error output:

ERROR in ./src/moduleA.js

There is a circular build dependency, which makes it impossible to create this module

Problems with current behavior:

• ❌ No indication of which other modules are involved
• ❌ No dependency chain shown
• ❌ No file paths or line numbers for other modules in the cycle
• ❌ No suggestions on how to fix it
• ❌ Developer must manually trace through all imports to find the cycle

Impact:

• In small projects: 10-15 minutes to find and fix
• In large projects: 30 minutes to several hours
• Frustrating developer experience
• Wastes significant development time

Environment

**Manual Environment Information:**

System:
  OS: Windows 10 10.0.19045
Binaries:
  Node: 22.16.0
  npm: [your npm version]
Packages:
  webpack: 5.104.1


**Webpack version:** 5.104.1

**Node version:** 22.16.0

**Operating System:** Windows 10

**Package Manager:** npm / yarn (specify which one you use)

Is this a regression?

None

Last Working Version

No response

Additional Context

Current Implementation Details

Code Location:

• Error class: lib/errors/BuildCycleError.js
• Detection logic: lib/Compilation.js (around line 2348)
• Error formatting: lib/formatLocation.js

Current BuildCycleError implementation:

class BuildCycleError extends WebpackError {
  constructor(module) {
    super("There is a circular build dependency, which makes it impossible to create this module");
    this.name = "BuildCycleError";
    this.module = module;
  }
}

Problem: Only stores the module that triggered the error, not the full dependency chain.

Real-World Impact Examples

Example 1: Small Project (10-20 files)

• Developer gets circular dependency error
• Must manually check each file's imports
• Time to fix: 10-15 minutes
• With enhanced error: 2-3 minutes (immediate visibility)

Example 2: Medium Project (100-200 files)

• Circular dependency in utility modules
• Error shows only one file
• Developer traces through 15+ files to find cycle
• Time to fix: 30-45 minutes
• With enhanced error: 5 minutes (full chain visible)

Example 3: Large Project (500+ files)

• Circular dependency in component library
• Multiple entry points
• Complex dependency graph
• Time to fix: 1-3 hours (or more)
• With enhanced error: 10-15 minutes (clear path shown)

Comparison with Other Tools

TypeScript:

• Shows full error chain
• Provides file paths and line numbers
• Example: "Circular reference detected: A.ts -> B.ts -> A.ts"

ESLint:

• Shows dependency relationships
• Clear error messages with context

Webpack (Current):

• Generic message only
• No chain information
• No actionable guidance

Workarounds (Current Solutions)

Workaround 1: Manual Tracing

• Open each file mentioned in error
• Check all imports
• Follow the chain manually
• Problem: Extremely time-consuming, error-prone

Workaround 2: Use External Tools

• Install madge to detect circular dependencies: npx madge --circular src/
• Use dependency-cruiser for dependency analysis
• Problem: Requires additional tools, not integrated with webpack

Workaround 3: Add Custom Plugin

• Create custom plugin to track dependencies
• Log dependency chains during build
• Problem: Complex, requires deep webpack knowledge

Proposed Solution Details

Enhancement approach:

1. Track dependency chain during module resolution
2. Store full chain in BuildCycleError
3. Format chain with file paths and line numbers
4. Add suggestions based on common patterns

Implementation considerations:

• Use existing formatLocation utility for location formatting
• Leverage module graph information already available
• Add chain tracking to circular dependency detection logic
• Format output similar to other webpack errors

Example enhanced error format:

ERROR in Circular dependency detected

Circular dependency chain:
  ./src/components/Button.js (line 5: import Icon from './Icon')
    → ./src/components/Icon.js (line 12: import { Button } from './Button')
      → ./src/components/Button.js (line 5)

To fix this circular dependency:
  💡 Extract shared code to a separate module (e.g., ./src/components/shared.js)
  💡 Use dynamic imports: const Icon = () => import('./Icon')
  💡 Refactor component structure to remove mutual dependencies

Benefits

For Developers:

• ✅ Saves 10 minutes to several hours per circular dependency
• ✅ Faster debugging and resolution
• ✅ Better understanding of code structure
• ✅ Reduced frustration

For Teams:

• ✅ Faster onboarding (new developers can fix issues quickly)
• ✅ Less time spent on debugging
• ✅ Better code quality (easier to identify architectural issues)

For Webpack:

• ✅ Improved developer experience
• ✅ Fewer support questions
• ✅ Better reputation as developer-friendly tool
• ✅ Aligns with modern tooling standards

Related Issues

• Similar error message improvements in webpack discussions
• Community requests for better debugging information
• Part of broader effort to improve webpack DX (Developer Experience)

Technical Notes

• Non-breaking change: Fully additive, doesn't affect existing functionality
• Performance impact: Minimal (dependency chain already tracked during resolution)
• Backward compatible: Existing error handling remains unchanged
• Implementation complexity: Medium (requires tracking and formatting logic)

Testing Scenarios

Test cases to consider:

1. Simple 2-module cycle (A → B → A)
2. Complex multi-module cycle (A → B → C → D → A)
3. Cycle with nested dependencies
4. Cycle in different entry points
5. Cycle with dynamic imports
6. Cycle in node_modules (if applicable)

---

Additional Notes

• This affects all developers using webpack
• More impactful in large codebases
• Aligns with webpack's goal of better developer experience
• Non-breaking change (additive enhancement)
• Would complement other error message improvements

[alexander-akait]

PR welcome, moved to ideas, because AI generated too