CircleCI "Could not find a .circleci/config.yml" - Fix

CircleCI looked for .circleci/config.yml at the repository root and did not find it. No pipeline can run without that file in the expected location on the built ref.

What this error means

A push triggers nothing, or CircleCI reports it could not find a config file. The directory is misnamed, the file is in a subfolder, or it exists only on a branch CircleCI is not building.

CircleCI UI

Could not find a .circleci/config.yml file.
Make sure it exists at the root of your repository.

Common causes

File missing or in the wrong place

CircleCI only reads .circleci/config.yml at the repo root. A file at the root, in circleci/ (no dot), or under a subdirectory is not picked up.

Wrong filename or extension

It must be exactly config.yml. config.yaml, Config.yml, or circle.yml (the old v1 name) are not recognized by current CircleCI.

Config exists only on another branch

If you added the config on a feature branch but pushed a different branch, that ref has no config and nothing runs.

How to fix it

Place the file at the canonical path

Terminal

# from the repo root
mkdir -p .circleci
git mv config.yaml .circleci/config.yml   # if misnamed/misplaced
git add .circleci/config.yml

Confirm the project is set up and building the branch

Check the project is followed/set up in the CircleCI UI.
Confirm the branch you pushed actually contains .circleci/config.yml.
Verify the GitHub/Bitbucket checkout key and webhook are connected.

How to prevent it

Keep .circleci/config.yml at the repo root, spelled exactly.
Add the config in the same PR that enables the project.
Validate the path in code review so it is never moved by accident.