GitHub Actions "recursive reusable workflows are not allowed"

By Daniel Zoghalchali·Latchkey

A reusable workflow call forms a cycle - directly or through a chain - which GitHub forbids. Reusable workflows also have a maximum nesting depth that a deep chain can exceed.

What this error means

A run fails with "recursive reusable workflows are not allowed", or an error about exceeding the reusable-workflow nesting limit, when a called workflow ends up calling back into the chain.

Error: recursive reusable workflows are not allowed:
.github/workflows/build.yml -> .github/workflows/build.yml

Common causes

A workflow calls itself or loops

A reusable workflow that uses: its own path, or a chain A -> B -> A, forms a cycle that GitHub rejects.

Nesting depth exceeded

Reusable workflow calls can only nest so deep. A long chain of called workflows can hit the limit even without a true cycle.

How to fix it

Break the call cycle

Restructure so no reusable workflow calls back into its own chain - factor shared logic into a leaf workflow or composite action.

# caller.yml
jobs:
  build:
    uses: ./.github/workflows/build.yml   # build.yml must not call caller.yml
    with:
      target: release

Flatten deep chains

1. Reduce the depth of nested reusable-workflow calls to stay under the limit.
2. Move common steps into a composite action, which does not count the same way.
3. Map the call graph to confirm there is no loop.

How to prevent it

• Keep reusable-workflow call graphs acyclic.
• Limit nesting depth; prefer composite actions for shared steps.
• Document the intended call chain so cycles are obvious.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions