Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker compose cannot find your Compose file

Errorno configuration file provided: not found

Short answer

Compose found no Compose file where it looked. It checks the current directory and its parents for compose.yaml, compose.yml, docker-compose.yaml or docker-compose.yml. Run the command from the project folder, rename the file to one of those names, or pass the path with -f or the COMPOSE_FILE variable.

  • Applies to Docker Compose 2.3x, Docker Desktop 4, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the folder you are in and the Compose-looking files in it. If nothing is listed, that is the whole problem.

    pwd
    ls -la | grep -i -E "compose|docker"
  2. 2Match what you see, then jump to its fix

    1. 1pwd shows a folder that has no Compose file, for example the home folder or a src subfolder of another projectYou are in the wrong folderFix
    2. 2ls shows something like docker-compose.dev.yml, compose.yaml.txt or compose.yamllThe file has a name Compose does not look forFix
    3. 3The same command works in your terminal and fails in a cron job, a Makefile target, or a CI jobA script or CI step runs from another working directoryFix

What does the error look like?

  • no configuration file provided: not found

Cause 1 of 3

You are in the wrong folder

1Check

Compose walks up from the working directory through the parent folders. A file in a sibling or child folder is never found.

find . -maxdepth 2 -name 'compose.y*ml' -o -maxdepth 2 -name 'docker-compose.y*ml'

2Fix

Change into the folder that holds the file, or name the file explicitly so the folder no longer matters.

cd ~/projects/my-app
docker compose up -d
# or, from anywhere:
docker compose -f ~/projects/my-app/compose.yaml up -d

3Verify

Compose lists the services it read from the file.

docker compose config --services

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The file has a name Compose does not look for

1Check

Only four names are tried by default: compose.yaml (preferred), compose.yml, docker-compose.yaml and docker-compose.yml. Windows editors sometimes add .txt, and a hidden extension makes it easy to miss.

ls -la | grep -i compose

2Fix

Rename the file to a default name, or give the real name with -f. The COMPOSE_FILE variable does the same as -f.

mv docker-compose.dev.yml compose.yaml
# or keep the name:
docker compose -f docker-compose.dev.yml up -d
# or for the whole shell session:
export COMPOSE_FILE=docker-compose.dev.yml

3Verify

The command now runs without the error.

docker compose config --quiet && echo ok

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

A script or CI step runs from another working directory

1Check

The job's working directory is not the project folder. Print it from inside the job.

pwd && ls

2Fix

Pass the file with -f, and set --project-directory if relative paths inside the file should resolve against the project folder. By default that directory is where the first Compose file lives.

docker compose -f /srv/my-app/compose.yaml --project-directory /srv/my-app up -d

3Verify

Run the job once and confirm the services start.

docker compose -f /srv/my-app/compose.yaml ps

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Name the file compose.yaml, the preferred name, and keep it in the project root.
  • In scripts and CI, always pass -f with an absolute path.
  • Turn on file extensions in the Windows file manager so a stray .txt shows up.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Servers

A dev container port does not open in the browser when Docker runs on a remote host

If your application only accepts calls from localhost, it will reject connections from published ports

Three things usually break it: the app listens only on localhost inside the container, so published ports are rejected; you open the container port instead of the mapped localhost port VS Code shows; or you changed appPort or a Compose ports list and did not rebuild.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.