Troubleshooting the no configuration file provided: not found Error in Docker Compose

1. Overview

When working with Docker Compose, it’s easier to manage multi-container Docker applications. With its help, we get to define services, networks, and volumes in a docker-compose.yml file, and spin up complex environments with a single command.

Occasionally, we may encounter the error no configuration file provided: not found. For instance, the error may appear when using commands such as docker compose logs or docker compose ps. In all cases, it usually happens when Docker Compose can’t find the configuration file.

In this tutorial, we discuss what causes the no configuration file provided: not found error, how to reproduce it, and then show steps we can follow to resolve such issues.

2. Reproducing the Configuration File Error

Typically, the docker compose command searches for the docker-compose.yml configuration file in the current working directory. If it doesn’t find one, it throws the error no configuration file provided: not found.

2.1. Simple Docker Compose Setup

To begin with, let’s create a directory for the project:

$ mkdir example-project && cd example-project

Next, let’s draft a docker-compose.yml file and save it inside the working directory:

$ cat docker-compose.yml
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

After creating the Compose file, let’s run the application:

$ docker compose up -d
[+] Running 9/9
 ✔ web Pulled                                                                                             13.2s
   ✔ 9824c27679d3 Pull complete                                                                            1.9s
   ✔ a5585638209e Pull complete                                                                            2.6s
   ✔ fd372c3c84a2 Pull complete                                                                            3.1s
   ✔ 958a74d6a238 Pull complete                                                                            3.5s
   ✔ c1d2dc189e38 Pull complete                                                                            3.9s
   ✔ 828fa206d77b Pull complete                                                                            4.4s
   ✔ bdaad27fd04a Pull complete                                                                            4.9s
   ✔ f23865b38cc6 Pull complete                                                                            8.4s
[+] Running 2/2
 ✔ Network example-project_default  Created                                                                0.4s
 ✔ Container example-project-web-1  Started                                                                4.6s

Further, we can check the logs within the same directory:

$ docker compose logs
web-1  | /docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
...
web-1  | 2025/08/08 03:03:17 [notice] 1#1: start worker process 32
web-1  | 2025/08/08 03:03:17 [notice] 1#1: start worker process 33

From the output above, we can see that the command works and displays the logs.

2.2. Trigger the Error

To trigger the error, let’s first navigate one directory up from the current working directory:

$ cd ..

Now, let’s recheck the logs:

$ docker compose logs
no configuration file provided: not found

Thus, we now get an error since the docker compose command is looking for a configuration file in the current directory. However, it doesn’t know what configuration to use because we’re no longer in the directory containing the docker-compose.yml file.

3. Common Fixes for the Configuration File Error

Let’s have a look at a few ways to fix the error no configuration file provided: not found.

3.1. Execute Commands in the Right Directory

Perhaps the simplest way to resolve the error is to ensure that we’re inside the directory containing the docker-compose.yml file before running any commands:

$ cd example-project && docker compose logs
web-1  | /docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
...
web-1  | 2025/08/08 03:03:17 [notice] 1#1: start worker process 32
web-1  | 2025/08/08 03:03:17 [notice] 1#1: start worker process 33

Above, we navigate to the directory holding the config file and then recheck the logs. Docker Compose now manages to locate the default config file.

3.2. Use the –project-directory Flag

Instead of utilizing the cd command to manually navigate to the correct directory, we can inform Docker Compose where to find the project with the help of the –project-directory flag.

For example, if we were to use the first approach we discussed about executing commands in the right directory, we might execute a chain of commands to still remain in the current one:

$ cd ./example-project && docker compose logs && cd ..

Above, we navigate into the example-project directory, check the logs, and navigate back to the parent directory. With the –project-directory flag, however, we can simply run a single command:

$ docker compose --project-directory ./example-project logs

The command above works just like if we had run it within the example-project directory. To clarify, it treats ./example-project as the working directory and searches for the docker-compose.yml file inside it.

We can use the –project-directory flag to streamline workflows:

• writing automation scripts or CI/CD jobs
• executing Docker Compose commands from a parent or external directory
• managing multiple Compose projects from a single control script or interface

It’s usually cleaner, more flexible, and avoids context-switching in scripts or terminal sessions.

3.3. Use the -f Flag

In case we need to run the command from another directory, we can use the -f flag to explicitly point to the Compose file:

$ docker compose -f example-project/docker-compose.yml logs

We can utilize this approach when running Docker Compose commands from a different directory or as part of an automated process. For instance, in shell scripts or CI/CD pipelines where the working directory may not be the same as the directory containing the docker-compose.yml file.

Additionally, we can use the -f flag to work with multiple Compose files, such as a base file and an override file. In such a scenario, we can chain multiple -f options to ensure Docker Compose loads the full configuration:

$ docker compose -f docker-compose.yml -f docker-compose.override.yml logs

Docker Compose merges the files in the order we specify them, enabling the second file to override or extend the configuration from the first.

If we’re running the command from outside the project directory, we need to provide the full or relative paths to both files:

$ docker compose -f ./example-project/docker-compose.yml -f ./example-project/docker-compose.override.yml logs

With the help of this approach, we can ensure Docker services start with the correct configuration, irrespective of where we execute the command from.

3.4. Set the COMPOSE_FILE Environment Variable

Critically, we can also indicate the Compose file via an environment variable:

$ export COMPOSE_FILE=example-project/docker-compose.yml

Now, if we navigate one directory up from the current working directory and recheck the logs, we get the expected logs output. This approach works well if we need to run multiple commands and want to avoid repeating the -f flag each time.

4. Checking Whether the Compose File Is Reachable

In case we’re unsure whether Docker Compose successfully detects the docker-compose.yml file, we can run a command to check that:

$ docker compose config
name: example-project
services:
  web:
    image: nginx:alpine
    networks:
      default: null
    ports:
      - mode: ingress
        target: 80
        published: "8080"
        protocol: tcp
networks:
  default:
    name: example-project_default

The command tries to load and validate the Compose configuration from the current working directory. If the configuration file exists and is correct, it outputs a fully resolved version of the Compose file containing any defaults, variable substitutions, and merged overrides.

Meanwhile, we get the no configuration file provided: not found error if Docker Compose fails to find the configuration file. Thus, we can either navigate to the correct directory or specify the location of the Compose file explicitly.

5. Conclusion

In this article, we dove into troubleshooting the no configuration file provided: not found error.

When Docker Compose fails to find the docker-compose.yml configuration file in the current directory, it throws the error in question. To resolve the issue, we can choose to navigate to the correct directory before running commands or use the –project-directory flag to point Docker Compose to the right directory. Also, we can apply the -f flag to explicitly specify the path to one or more Compose files. An additional approach includes setting the COMPOSE_FILE environment variable for cases when multiple commands need to reuse the same configuration file path.

Thus, understanding how Docker Compose locates the configuration file helps us avoid common errors.