# Docker Compose "service refers to undefined volume" in CI

> Fix Docker Compose "service X refers to undefined volume Y" in CI - a named volume used by a service but never declared in the top-level volumes section.

Source: https://latchkey.dev/learn/docker/docker-compose-service-refers-to-undefined-volume  
Updated: 2026-06-25

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.

## Diagnose it: read the resolved config, not the file you wrote

Compose merges override files, interpolates variables, and applies defaults before it does anything. Most Compose failures in CI are visible in the resolved configuration and invisible in the source file, because the value you are debugging came from an unset variable that quietly became an empty string.

```Terminal
# the fully merged, interpolated configuration Compose will actually run
docker compose config

# fail loudly on unset variables instead of silently interpolating empty
docker compose --env-file .env config --quiet || echo "invalid"

# which override files were picked up
docker compose config --services
```

> An unset variable interpolates to an empty string rather than erroring, so `image: myapp:${TAG}` becomes `myapp:` and fails later with a confusing reference error. `docker compose config` shows you the empty value directly.

## Bind mounts behave differently on a runner

- A relative bind source is resolved against the compose file location, not the working directory of the shell that invoked it.
- The host path must exist before `up`. Compose creates missing directories for named volumes but not for bind mounts, and the failure surfaces as a mount error rather than a missing-path error.
- On a CI runner the workspace path differs from your machine, so any absolute host path in a compose file is a portability bug waiting for its first CI run.
- Prefer named volumes for anything that does not genuinely need to be read from the host. They remove the whole class of problem.

## FAQ

### What causes Docker Compose "service refers to undefined volume" in CI?

There are 2 common causes: the named volume is not declared at the top level and a typo between the mount and the declaration. A service uses pgdata:/path, but there is no pgdata: under the top-level volumes: key.

### How do I fix Docker Compose "service refers to undefined volume" in CI?

There are 2 fixes depending on which cause you have: declare the named volume and or use a bind mount instead. Work through them in order, since the first is the most common.

### What does Docker Compose "service refers to undefined volume" in CI actually mean?

A docker compose up/config fails during validation with service "X" refers to undefined volume "Y": invalid compose project.

### How do I stop Docker Compose "service refers to undefined volume" in CI happening again?

Declare every named volume in the top-level volumes: section. The prevention section lists 3 changes that keep it from recurring.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt