service "db" refers to undefined volume "dbdata": invalid compose project

Fix service "db" refers to undefined volume "dbdata": invalid compose project (docker-compose)

TL;DR

The service mounts a named volume that is missing from the top-level volumes: section. Add the volume name under top-level volumes: (an empty entry is enough). Bind mounts and bare paths never need this, only named volumes.

The error, verbatim:

service "db" refers to undefined volume "dbdata": invalid compose project

Steps

1. Confirm which volume is undeclared:

   docker compose config

   Success check: The error names the exact service and volume.

2. Declare the volume at the top level of the compose file:

   grep -n -A5 "^volumes:" docker-compose.yml

   Success check: dbdata: now appears under top-level volumes:.

3. Re-validate and bring the stack up:

   docker compose config

   Success check: The parsed file prints with no errors.

When to use

You hit this exact error while using docker-compose. The trigger list below matches your situation.

When NOT to use

If the error text differs, or the failure is in a different tool (e.g. a Docker daemon error when you only need the compose fix), find the skill for that exact error instead.

Tool compatibility

docker-compose v1 and Compose v2. Any OS.

Variant phrasings

refers to undefined volume

invalid compose project

Root cause

The service mounts a named volume (a bare name like dbdata:/var/lib/db), but the name is never declared in the top-level volumes: section. Compose treats undeclared named volumes as a project error rather than silently creating an empty volume under a possibly-misspelt name.

Edge cases

• Bind mounts (./data URIs/data, /abs/path:/x) and bare container paths (/data) need no declaration; only bare names do.
• A misspelled name on either side triggers this: the volume gets created under the misspelt name on older versions.
• With extends:, top-level volumes: are NOT inherited; each entry-point file must declare the volume.

Where this came from

Resolved from the public discussion at https://stackoverflow.com/questions/69867166 (so:69867166).