What causes "invalid image source, source cannot be empty" in docker/cli?

Add a source with the image reference, e.g. source: alpine:latest.

invalid image source, source cannot be empty

Error message

invalid image source, source cannot be empty

What it means

Raised at the top of handleImageToMount when a mount of type 'image' has an empty source. For image mounts the source must name the container image to mount, so unlike anonymous volumes there is no sensible default and the converter rejects the entry immediately.

Source

Thrown at cli/compose/convert/volume.go:98

		return result, nil
	}

	result.VolumeOptions.Labels = addStackLabel(namespace, stackVolume.Labels)
	if stackVolume.Driver != "" || stackVolume.DriverOpts != nil {
		result.VolumeOptions.DriverConfig = &mount.Driver{
			Name:    stackVolume.Driver,
			Options: stackVolume.DriverOpts,
		}
	}

	return result, nil
}

func handleImageToMount(volume composetypes.ServiceVolumeConfig) (mount.Mount, error) {
	result := createMountFromVolume(volume)

	if volume.Source == "" {
		return mount.Mount{}, errors.New("invalid image source, source cannot be empty")
	}
	if volume.Volume != nil {
		return mount.Mount{}, errors.New("volume options are incompatible with type image")
	}
	if volume.Bind != nil {
		return mount.Mount{}, errors.New("bind options are incompatible with type image")
	}
	if volume.Tmpfs != nil {
		return mount.Mount{}, errors.New("tmpfs options are incompatible with type image")
	}
	if volume.Cluster != nil {
		return mount.Mount{}, errors.New("cluster options are incompatible with type image")
	}
	if volume.Image != nil {
		result.ImageOptions = &mount.ImageOptions{
			Subpath: volume.Image.Subpath,
		}
	}

View on GitHub (pinned to e9452d6e78)

Solutions

Add a source with the image reference, e.g. source: alpine:latest.
If the source uses variable substitution, ensure the variable is set in the deploy environment ('docker compose config' shows the resolved value).
If you wanted an anonymous volume instead, change type to volume.

Example fix

# before
volumes:
  - type: image
    target: /mnt/img
# after
volumes:
  - type: image
    source: alpine:latest
    target: /mnt/img

When it happens

Trigger: 'docker stack deploy' with a service volume entry of type: image whose source key is missing, empty, or resolves to an empty string after variable substitution.

Common situations: Forgetting the source: line when trying the newer image-mount feature; an unset environment variable like source: ${IMAGE_REF} expanding to empty; confusing image mounts with anonymous volumes, which do allow empty source.

Related errors

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/eaf88cfd31529b6f.json. Report an issue: GitHub.