GitHub Actions "reusable workflow exceeds nesting limit (4)"

By Daniel Zoghalchali·Latchkey

Reusable workflows can call other reusable workflows, but the call chain is limited to four levels. A deeper chain fails validation. This is a hard limit, not a transient failure.

What this error means

A workflow that calls reusable workflows which call further reusable workflows fails because the nesting depth exceeds the maximum.

Error: The maximum number of nested reusable workflows (4) has been exceeded.

Common causes

Call chain deeper than four levels

The top workflow plus nested reusable calls exceed the four-level depth limit.

Reusable workflows over-decomposed

Splitting logic into many thin reusable layers pushes the chain past the limit.

How to fix it

Flatten the reusable chain

1. Collapse intermediate reusable layers so the chain is at most four deep.
2. Inline shallow wrappers that add no value.
3. Move shared steps into a composite action instead of another nesting level.

# Flatten: caller -> deploy-reusable (which calls at most build-reusable)
jobs:
  deploy:
    uses: ./.github/workflows/deploy-reusable.yml
    secrets: inherit

How to prevent it

• Keep reusable workflow chains shallow (within four levels).
• Prefer composite actions over extra reusable-workflow nesting for shared steps.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions