# 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:

```text
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).