Java "StackOverflowError" in CI - Fix Deep Recursion / -Xss

A thread exhausted its call stack. Usually that is unbounded or accidental infinite recursion; occasionally it is a legitimately deep call chain that needs a larger -Xss (per-thread stack size).

What this error means

A test or app step fails with java.lang.StackOverflowError and a very long, repeating stack trace showing the recursive cycle. It is deterministic for the same input.

Exception in thread "main" java.lang.StackOverflowError
    at com.example.Node.depth(Node.java:31)
    at com.example.Node.depth(Node.java:31)
    at com.example.Node.depth(Node.java:31)   ... (repeats)

Common causes

Infinite or unbounded recursion

A missing base case, a cyclic data structure, or mutual recursion never terminates, growing the stack until it overflows. This is a code bug.

Legitimately deep recursion with a small stack

A correct but deep algorithm (parsing, tree traversal) can exceed the default ~512 KB–1 MB stack, especially with a reduced -Xss.

How to fix it

Fix the recursion

The repeating frames in the trace name the cycle. Add a base case, break the cycle, or convert to iteration.

# the repeated frame (e.g. Node.depth at one line) is the recursion to fix

Raise -Xss for genuinely deep call chains

If the recursion is correct and bounded, give threads a larger stack.

java -Xss2m -jar app.jar
# Maven Surefire forked JVM:
# mvn -B test -DargLine="-Xss2m"

How to prevent it

• Ensure every recursive method has a reachable base case.
• Prefer iteration for unbounded-depth traversals.
• Set -Xss deliberately if a correct algorithm needs a deeper stack.

Related guides