Maven "cyclic reference" in the reactor in CI

By Daniel Zoghalchali·Latchkey

Maven builds reactor modules in dependency order, which requires a directed acyclic graph. A cycle (module A depends on B, B depends on A) has no valid order, so the build aborts before any module compiles.

What this error means

mvn fails immediately with "The projects in the reactor contain a cyclic reference: Edge between 'Vertex{...A}' and 'Vertex{...B}' introduces to cycle ...".

[ERROR] The projects in the reactor contain a cyclic reference:
Edge between 'Vertex{label='com.example:module-a:1.0.0'}' and
'Vertex{label='com.example:module-b:1.0.0'}' introduces to cycle:
com.example:module-a:1.0.0 --> com.example:module-b:1.0.0 --> com.example:module-a:1.0.0 -> [Help 1]

Common causes

Two modules depend on each other

Module A declares a dependency on B and B declares a dependency on A, forming a cycle the reactor cannot order.

A new cross-module dependency closed a loop

A recently added dependency between sibling modules created a circular reference that did not exist before.

How to fix it

Break the cycle by extracting shared code

1. Identify the two modules in the "introduces to cycle" message.
2. Move the code they both need into a new lower-level module.
3. Have both depend on the new module, not on each other.

Remove the dependency that closed the loop

If the back-edge is accidental, delete that <dependency> so the graph is acyclic again.

mvn -B validate

How to prevent it

• Keep module dependencies a directed acyclic graph.
• Extract shared code into a base module instead of cross-referencing.
• Review new cross-module dependencies for cycles.

Frequently asked questions

Related guides

References

• Apache Maven guides
• Gradle user manual
• GitHub Actions documentation