Docker Compose "service refers to undefined volume" in CI

By Daniel Zoghalchali·Latchkey

A service mounts a named volume that Compose does not know about. Named volumes must be declared in the top-level volumes: section, and this one is missing.

What this error means

A docker compose up/config fails during validation with service "X" refers to undefined volume "Y": invalid compose project. Nothing starts because the volume reference cannot be resolved.

service "db" refers to undefined volume pgdata: invalid compose project
# the service mounts "pgdata:/var/lib/postgresql/data" but there is no
# top-level volumes: pgdata:

Common causes

The named volume is not declared at the top level

A service uses pgdata:/path, but there is no pgdata: under the top-level volumes: key. Compose treats the bare name as a named volume that must be declared.

A typo between the mount and the declaration

The volume is declared under one name and referenced under a slightly different one, so the reference resolves to nothing.

How to fix it

Declare the named volume

Add the volume to the top-level volumes: section.

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

volumes:
  pgdata:

Or use a bind mount instead

If you meant a host path, use a relative/absolute path (starting with ./ or /) rather than a bare name.

volumes:
  - ./data:/var/lib/postgresql/data   # bind mount, no top-level declaration needed

How to prevent it

• Declare every named volume in the top-level volumes: section.
• Run docker compose config in CI to catch undefined volumes early.
• Keep volume names consistent between the mount and the declaration.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation