GitHub Actions "The workflow must contain at least one job with no dependencies"

By Kaveh Alemi·Latchkey

A workflow's job graph must have a root - at least one job with no needs - so execution can begin. If every job depends on another, the graph has a cycle and cannot start.

What this error means

The workflow fails to start with "The workflow must contain at least one job with no dependencies", typically after adding a needs that closes a loop.

Error: The workflow must contain at least one job with no dependencies.

Common causes

Cyclic needs graph

Jobs reference each other through needs in a loop (A needs B, B needs A), so no job can start.

Every job has a needs

No job was left without needs, so there is no entry point to the graph.

How to fix it

Break the cycle and add a root job

1. Map out the needs graph and find the loop.
2. Remove the needs that closes the cycle.
3. Ensure at least one job has no needs.

jobs:
  build:        # root job, no needs
    runs-on: ubuntu-latest
    steps: [{ run: make }]
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps: [{ run: make deploy }]

How to prevent it

• Keep the needs graph acyclic with a clear root job.
• Review needs edges when adding cross-job dependencies.
• Lint workflows for dependency cycles.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions