Home › Docker

service "app" refers to undefined volume data: invalid compose project (Docker) — how to fix

service "app" refers to undefined volume data: invalid compose project
service "web" refers to undefined network backend: invalid compose project

Quick fix: Declare it in a top-level volumes: (or networks:) section at zero indentation, e.g. volumes: followed by data:. If you meant a host folder, write it as a path: ./data:/var/lib/data — a bare name like data:/path is a named volume. Validate with docker compose config.

What it means

In Compose, a volume entry NAME:/container/path where NAME has no / or . prefix is a named volume. Named volumes and custom networks must be declared at the top level of the file. Compose v2 validates this before starting anything and stops with invalid compose project.

Cause 1: the top-level declaration is missing

services:
  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
# pgdata is never declared -> error

Fix:

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

volumes:
  pgdata:

Same for networks:

services:
  web:
    networks: [backend]

networks:
  backend:

Cause 2: you meant a host directory (bind mount)

volumes:
  - data:/app/data        # named volume "data"
  - ./data:/app/data      # host folder ./data
  - /srv/data:/app/data   # absolute host path

A host path must start with ., / or ~. On Windows, use ./data or C:/path/data.

Cause 3: indentation puts it in the wrong place

YAML indentation decides where a key belongs. Here volumes: is nested inside the db service, so it's a service-level setting, not a declaration:

services:
  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
  volumes:          # wrong: indented under services, looks like a service named "volumes"
    pgdata:

Top-level volumes: and networks: must start at column 0, same as services:. Use spaces, not tabs. A YAML validator shows the structure.

Cause 4: multiple compose files or profiles

With -f docker-compose.yml -f docker-compose.override.yml, the volume may be used in one file but declared only in a file you didn't pass. Check the merged result:

docker compose -f docker-compose.yml -f docker-compose.prod.yml config

docker compose config prints the fully resolved file, or the exact validation error.

Cause 5: using an existing volume/network created outside Compose

If the volume or network already exists (created by docker volume create or another project), declare it as external so Compose doesn't create or rename it:

volumes:
  pgdata:
    external: true
    name: my_existing_volume

networks:
  shared:
    external: true
    name: proxy_network

If it doesn't exist yet: docker network create proxy_network. Otherwise you'll get network not found.

Cause 6: variable substitution produced an unexpected name

volumes:
  - ${DATA_DIR}:/data

If DATA_DIR is unset, it becomes :/data (error), and if it's data without ./, it becomes a named volume. Set it in .env as DATA_DIR=./data, or use a default: ${DATA_DIR:-./data}:/data.

Verify

docker compose config --volumes
docker compose up -d
docker volume ls

Last updated 2026-11-13.