docker/compose · error

external volume %q not found

Error message

external volume %q not found

What it means

Error "external volume %q not found" thrown in docker/compose.

Source

Thrown at pkg/compose/create.go:221

}

// checkExternalVolumes validates that every external volume exists and returns
// their resolved names. External volumes carry no compose label and are
// therefore absent from the label-scoped observed state, so the reconciler needs
// them injected via setResolvedVolumes.
//
// Managed and legacy (unlabeled, name-matched) volumes are discovered by
// collectObservedState; their lifecycle is owned by the reconciliation plan, so
// this function performs no mutation on them.
func (s *composeService) checkExternalVolumes(ctx context.Context, project *types.Project) (map[string]string, error) {
	external := map[string]string{}
	for k, volume := range project.Volumes {
		if !volume.External {
			continue
		}
		if _, err := s.apiClient().VolumeInspect(ctx, volume.Name, client.VolumeInspectOptions{}); err != nil {
			if errdefs.IsNotFound(err) {
				return nil, fmt.Errorf("external volume %q not found", volume.Name)
			}
			return nil, err
		}
		external[k] = volume.Name
	}
	return external, nil
}

// warnUnmanagedVolumes warns about declared volumes backed by a live volume that
// this project does not own — either created outside Compose (no project label)
// or by another project. Such volumes are matched by name and reused untouched
// (see collectObservedState); the warning tells the user to set `external: true`
// to make the intent explicit.
func warnUnmanagedVolumes(project *types.Project, observed *ObservedState) {
	for k, volume := range project.Volumes {
		if volume.External {
			continue
		}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Create the external volume first: docker volume create <name>.
2. Check the volume name for typos, or remove external: true from the volume definition so Compose creates it.

When it happens

Trigger: A volume declared with 'external: true' in the compose file does not exist in the Docker engine when the service is created.

Common situations: The external volume was never created, was removed, or the name in the compose file (including project prefix handling) does not match the actual volume name.

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/c75da47081067f92. Report an issue: GitHub.