CircleCI "No workflow defined" - Nothing Runs

By Kaveh Alemi·Latchkey

CircleCI parsed and validated the config but found no workflow to run. The workflows: section is missing or empty, or every job is filtered out for the pushed branch/tag.

What this error means

A push triggers no jobs, or CircleCI reports no workflow is defined. The config may be valid, yet nothing is scheduled because there is no workflow that selects a job for this ref.

No workflow defined. Add a 'workflows' section to your .circleci/config.yml,
or no jobs were selected for this branch by the configured filters.

Common causes

Missing or empty workflows section

In config 2.1, jobs run via a workflows: section. Without it (or with an empty jobs list) nothing is scheduled.

Branch/tag filters exclude every job

If each job's filters only match other branches or tags, the pushed ref selects no job and no workflow runs.

How to fix it

Define a workflow that runs your jobs

version: 2.1
jobs:
  build:
    docker: [{ image: cimg/node:20.11 }]
    steps: [checkout, { run: npm test }]

workflows:
  ci:
    jobs:
      - build

Check filters cover the pushed ref

1. Review each job's filters.branches/filters.tags against the ref you pushed.
2. Add a job (or remove a too-narrow filter) so normal pushes run something.
3. Validate and push a test commit to confirm a workflow starts.

How to prevent it

• Always include a workflows: section with at least one always-on job.
• Keep branch/tag filters broad enough to cover default pushes.
• Validate config so an empty workflow is caught early.

Frequently asked questions

Related guides

References

• GitHub Actions documentation