Fix Docker Compose error: external volume could not be found

What this error means

You ran docker compose up (or docker-compose up) and saw:

ERROR: volume ... declared as external, but could not be found

Compose will not create external volumes. It expects the volume to already exist on the target Docker host and to be named exactly as specified. If it does not exist, or you are on a different Docker context or the name is mismatched, you get this error.

Quickstart fix

• List volumes and confirm the expected name:
  • sh docker volume ls docker volume ls --filter name=dbdata
• Create the missing volume:
  • sh docker volume create dbdata
• Or in compose, remove external: true so Compose creates the volume automatically.
• If the real volume has a different name (for example myapp_dbdata), set volumes.dbdata.name to that exact value.
• Ensure you are on the right Docker context or host.

Minimal working example (fail then fix)

This compose file fails because the volume is declared external but does not exist yet.

version: '3.9'
services:
  db:
    image: postgres:16
    volumes:
      - dbdata:/var/lib/postgresql/data
volumes:
  dbdata:
    external: true

Run:

docker compose up -d

You will see the external volume not found error.

Fix option A: create the volume explicitly.

docker volume create dbdata
docker compose up -d

Fix option B: let Compose manage the volume (remove external).

version: '3.9'
services:
  db:
    image: postgres:16
    volumes:
      - dbdata:/var/lib/postgresql/data
volumes:
  dbdata: {}

Compose will create a volume named project_dbdata (project is the Compose project name).

Fix option C: reference the existing name exactly.

version: '3.9'
services:
  db:
    image: postgres:16
    volumes:
      - dbdata:/var/lib/postgresql/data
volumes:
  dbdata:
    external: true
    name: myapp_dbdata

Step-by-step diagnosis

1. Identify the volume name expected by Compose

• Check the volumes section in compose. If external: true and no name is given, the expected name is the key (dbdata in the example).
• If name: is set, that is the required exact name.

1. Check whether the volume exists on the current Docker context

• sh docker context ls docker context show docker volume ls --format '{{.Name}}' | grep -E '^dbdata$'
• If the volume is missing, create it: docker volume create dbdata

1. Verify project name effects

• When external is false or omitted, Compose creates volumes prefixed by the project name, e.g., myapp_dbdata.
• If you previously created a volume via Compose without external, and now you set external: true dbdata, Compose will not find myapp_dbdata unless you set name: myapp_dbdata or run with the same project name.
• To match a prior project name: docker compose -p myapp up -d

1. Distinguish Compose vs Swarm

• docker compose up uses local volumes on the target host.
• docker stack deploy requires external volumes to pre-exist on every node or be provided by a volume driver that can provision them.

1. Confirm driver and scope if using non-local drivers

• For NFS, EBS, or other drivers, ensure the driver plugin is installed and the volume is created with the correct driver options on the target host or swarm.

Common scenarios and fixes

Reliable patterns

• If you want Compose to manage lifecycle per project, omit external and let it create project-scoped volumes.
• If you need a shared, stable volume name across multiple stacks or projects, use external: true and name: exact_name, and provision it ahead of time.
• Pin the project name in teams and CI with the -p flag or COMPOSE_PROJECT_NAME to avoid accidental volume name drift.

Pitfalls to avoid

• Assuming Compose will create external volumes: it will not.
• Forgetting the project name prefix: volumes created by Compose are often projectname_volumekey.
• Mixing contexts or hosts: a volume on docker-desktop is not on a remote Linux host.
• Typos or case differences in volume names: names are case sensitive.
• Using bind mounts as a quick fix for databases on macOS or Windows can be slow and fragile; prefer named volumes.

Performance notes

• Creating a named volume is cheap and fast. Use docker volume create in setup scripts rather than retrying compose up.
• For database workloads, named volumes are generally faster and more reliable than host bind mounts on macOS and Windows.
• Allowing Compose to create per-project volumes (no external) can speed up developer workflows by avoiding permission and cross-project conflicts.
• In Swarm or multi-host setups, prefer a proper volume driver that supports remote provisioning to avoid manual pre-creation on every node.

Tiny FAQ

• Why does Compose add a prefix to volume names?
  • When external is not used, Compose namespaces resources by project to avoid collisions.
• How do I know the final volume name?
  • Run docker compose ls to see the project name, then expect project_volumekey. Or inspect with docker volume ls.
• Can I share the same volume across multiple compose projects?
  • Yes. Declare external: true and set name: shared_name. Pre-create the volume once.
• Does docker-compose vs docker compose change behavior?
  • The error and fixes are the same. Prefer docker compose (v2) and the -p flag for consistent project names.