Maaz Zindani

Loading the index…

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

docker compose rejects a service that uses a volume nobody declared

Errorservice "db" refers to undefined volume pgdata: invalid compose project

Short answer

A short volume entry like data:/var/lib/data names a volume called data. Compose then expects a matching entry under the top-level volumes key. If it is missing, misspelled or indented wrongly, Compose stops. Declare the volume, fix the name, or write a host path if you meant a bind mount.

  • Applies to Docker Compose v2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List the volumes Compose actually found in the file. If the one you use is not in the list, the declaration is missing or nested in the wrong place.

    docker compose config --volumes
    docker compose config --quiet
  2. 2Match what you see, then jump to its fix

    1. 1The services block uses name:/path but there is no volumes: block at the left edge of the fileThe named volume is not declared at the top levelFix
    2. 2A volumes: block exists, but it sits under services or the spelling differs from the service's entryThe top-level volumes block is indented, or the name does not matchFix
    3. 3The left side of the mapping is a plain word such as data or app, not a pathYou meant a host folder, not a named volumeFix

What does the error look like?

  • service "db" refers to undefined volume pgdata: invalid compose project
  • Undefined volume with Docker Compose

Cause 1 of 3

The named volume is not declared at the top level

1Check

The docs say a named volume has to be declared in the top-level volumes element before several services can reuse it, and a service gets access only through its own volumes attribute.

grep -n -E '^volumes:|^services:|^  *- *[A-Za-z0-9_.-]+:/' docker-compose.yml

2Fix

Add the volume under a top-level volumes key. An empty entry is enough: the engine's default settings are used and Compose creates it on the first up.

services:
  db:
    image: postgres:17
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

3Verify

The volume now appears in the list.

docker compose config --volumes

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The top-level volumes block is indented, or the name does not match

1Check

volumes must be a sibling of services, at the same indentation. Names are matched exactly, so pgdata and pg_data are two different volumes.

docker compose config --volumes
grep -n -E 'volumes:|pg' docker-compose.yml

2Fix

Move the block to the left edge and use one spelling in both places.

services:
  db:
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

3Verify

Compose parses the file without the error.

docker compose config --quiet && echo OK

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

You meant a host folder, not a named volume

1Check

The left side can be a volume name or a host path. To avoid mixing them up, the docs say relative paths should always begin with . or .., so a plain word is read as a volume name.

grep -n -E '^\s+- [A-Za-z0-9_.-]+:/' docker-compose.yml

2Fix

Start the left side with ./ or an absolute path, and remove the entry from the top-level block if you added it only to silence the error.

services:
  web:
    volumes:
      - ./data:/var/lib/data

3Verify

The file parses and the folder shows inside the container.

docker compose config --quiet && echo OK
docker compose run --rm web ls /var/lib/data

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Run docker compose config --quiet before docker compose up.
  • Write ./ in front of every host path so a path is never mistaken for a volume name.
  • Declare every named volume in the same commit that first uses it.

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.