CircleCI Reusable Config "maximum recursion depth exceeded"

By Kaveh Alemi·Latchkey

CircleCI expands reusable commands and executors at config-processing time. If a command calls itself (directly or via a chain), expansion never terminates and CircleCI aborts with a recursion error.

What this error means

Config processing fails with a maximum recursion depth message, usually pointing at a command that ends up calling itself.

Error processing config: maximum recursion depth exceeded while
expanding command setup, which references itself via prepare -> setup.

Common causes

Command calls itself

A reusable command lists itself among its own steps.

Cycle through multiple commands

Command A calls B, which calls A, forming a loop.

How to fix it

Break the cycle

Refactor shared logic into a base command that neither side re-enters.

commands:
  base-setup:
    steps:
      - run: ./setup.sh
  prepare:
    steps:
      - base-setup   # no longer calls 'setup' which called 'prepare'

How to prevent it

• Keep reusable command call graphs acyclic.
• Factor shared steps into a leaf command.
• Review command references when refactoring.

Frequently asked questions

Related guides

References

• GitHub Actions documentation