CircleCI "Could not find a usable config" error

By Daniel Zoghalchali·Latchkey

CircleCI looked for .circleci/config.yml at the repository root and could not find a readable one. Either the file is missing, in the wrong path, or empty.

What this error means

The pipeline fails immediately with "Could not find a usable config.yml, you may have revoked the CircleCI OAuth app." or a "config file is empty" message.

Could not find a usable config.yml, you may have revoked the CircleCI OAuth app.
Please sign out of CircleCI and log back in with your VCS before continuing.

Common causes

The config file is missing or misplaced

CircleCI requires the file at .circleci/config.yml from the repo root; a different path or filename is not detected.

Revoked VCS access or wrong default branch

If CircleCI cannot read the repo (revoked OAuth) or the configured branch has no config, it reports the file as unusable.

How to fix it

Place config at the expected path

1. Confirm the file exists at .circleci/config.yml at the repo root.
2. Ensure it is committed on the branch being built.
3. Verify the file is non-empty and starts with version:.

git ls-files .circleci/config.yml
head -1 .circleci/config.yml

Re-authorize the VCS connection

If the message mentions revoked OAuth, sign out of CircleCI and reconnect the VCS so it can read the repo again.

How to prevent it

• Keep the config at .circleci/config.yml exactly.
• Commit the config on the branch you build.
• Re-authorize VCS access promptly after any token rotation.

Frequently asked questions

Related guides

References

• GitHub Actions documentation