Maaz Zindani

Loading the index…

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

docker compose build cannot find or read the Dockerfile

Errorfailed to read dockerfile

Short answer

Compose looks for the Dockerfile in the wrong place. The build context is resolved from the folder of the Compose file, and a relative dockerfile path is resolved from that context, not from the Compose file. Put the path pair right, or name the file with -f when you build with the plain docker CLI.

  • Applies to Docker Engine 27, Docker Compose v2.3x, Docker Desktop 4.4x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List the folder the Compose file sits in and the folder you named as the build context. The Dockerfile has to be in the context, or the dockerfile value has to lead to it from the context.

    ls -la
    grep -n -A3 "build:" compose.yaml
  2. 2Match what you see, then jump to its fix

    1. 1The service sets context to a sub folder and dockerfile to a path that already starts at the Compose file's folderdockerfile is written relative to the Compose file, not to the contextFix
    2. 2build.context is missing or wrong, so it defaults to the project directoryThe context points at a folder that has no DockerfileFix
    3. 3docker build . fails while the file exists under a different name or extensionThe Dockerfile has another name and the plain docker build does not know itFix

What does the error look like?

  • failed to read dockerfile
  • docker compose up or docker compose build stops before the first build step
  • the build works from one folder and fails from another

Cause 1 of 3

dockerfile is written relative to the Compose file, not to the context

1Check

Compose resolves a relative dockerfile path from the build context. With context: backend, a value of backend/Dockerfile is searched as backend/backend/Dockerfile.

grep -n -B1 -A4 "build:" compose.yaml
ls backend

2Fix

Write the dockerfile path as seen from the context folder. To use a Dockerfile that lives outside the context, walk back up with ..

services:
  api:
    build:
      context: backend
      dockerfile: Dockerfile
  worker:
    build:
      context: backend
      dockerfile: ../backend.Dockerfile

3Verify

Run the build again; the first step should now start.

docker compose build api

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The context points at a folder that has no Dockerfile

1Check

A relative context is read from the directory that contains the Compose file. If context is not set, it is the project directory itself. Check which folder you run compose from.

pwd
ls Dockerfile

2Fix

Set context explicitly to the folder that holds the Dockerfile and the files it copies, or run the command from the project directory.

services:
  api:
    build:
      context: ./services/api

3Verify

Build from the project directory.

docker compose build

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The Dockerfile has another name and the plain docker build does not know it

1Check

docker build uses the -f (or --file) option to choose the Dockerfile. Without it the builder looks for the default name in the context. A file saved as Dockerfile.txt or with different letter case is not found on Linux.

ls -la | grep -i dockerfile

2Fix

Rename the file to Dockerfile, or point to it with -f and give the context separately.

docker build -f Dockerfile.dev -t my-app .

3Verify

The build starts and prints its first step.

docker build -f Dockerfile.dev -t my-app .

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Keep one Dockerfile per context folder and name it Dockerfile, so no dockerfile key is needed.
  • Write context and dockerfile as a pair and read them together: context from the Compose file, dockerfile from the context.
  • Run compose from the project directory in scripts and CI.

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

Next step

Want this handled for good?

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