GitHub Actions "nesting level too deep" - Reusable Workflow Nesting Limit

By Daniel Zoghalchali·Latchkey

A chain of reusable workflows calling reusable workflows exceeds the maximum nesting depth GitHub allows, so the run is rejected at compile time.

What this error means

The workflow fails to start with an error about the reusable workflow nesting level being too deep, naming the call chain. No job executes because the graph is invalid.

error: The nesting level of reusable workflows has exceeded the maximum
allowed value. Reduce the depth of the reusable workflow call chain.

Common causes

Too many reusable-workflow hops

A reusable workflow may call other reusable workflows, but the total connected chain is capped. A deep A→B→C→D→E… graph crosses the limit.

Accidental fan-out through shared callers

Shared "wrapper" reusable workflows that each call another wrapper quietly add depth, pushing a seemingly shallow caller over the limit.

How to fix it

Flatten the call chain

Collapse intermediate wrapper workflows so the caller invokes the leaf reusable workflow directly instead of through several layers.

jobs:
  build:
    # call the leaf reusable workflow directly, not via a wrapper-of-a-wrapper
    uses: my-org/ci/.github/workflows/build.yml@v1
    secrets: inherit

Replace deep nesting with composite actions

1. Move shared step logic into a composite action instead of another reusable-workflow layer.
2. Keep the reusable-workflow chain shallow - caller to leaf where possible.
3. Audit shared wrappers for hidden extra hops.

How to prevent it

• Prefer composite actions over extra reusable-workflow layers for shared steps.
• Document the call depth of shared reusable workflows.
• Keep caller-to-leaf chains as short as the feature allows.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions