bind options are incompatible with type image

Error message

bind options are incompatible with type image

What it means

Returned by handleImageToMount (volume.go:103-104) when a Compose service volume is type: image but also carries a 'bind' sub-options block (propagation). Bind options only apply to type: bind mounts; combining them with an image mount is rejected during conversion.

Solutions

Remove the 'bind:' sub-key from the image-type mount.
If propagation semantics are needed, use type: bind with a host path source.
Validate with 'docker compose config'.

Example fix

# before
volumes:
  - type: image
    source: myimg:latest
    target: /app
    bind:
      propagation: shared

# after
volumes:
  - type: image
    source: myimg:latest
    target: /app

Defensive patterns

Strategy: validation

Validate before calling

// Ensure an image-type mount does not carry bind options.
func validateImageMount(v composetypes.ServiceVolumeConfig) error {
    if v.Type == "image" && v.Bind != nil {
        return errors.New("bind options are incompatible with type image")
    }
    return nil
}

Type guard

// imageMountHasNoForeignOptions reports whether an image-type mount omits volume/bind/tmpfs/cluster.
func imageMountHasNoForeignOptions(v composetypes.ServiceVolumeConfig) bool {
    if v.Type != "image" {
        return true
    }
    return v.Volume == nil && v.Bind == nil && v.Tmpfs == nil && v.Cluster == nil
}

Prevention

Bind propagation only applies to type: bind; remove it from image mounts.
Do not reuse option-block anchors across bind and image mounts.
Run 'docker compose config' to surface the conflict.

When it happens

Trigger: In docker-compose.yml: { type: image, source: myimg:latest, target: /app, bind: { propagation: shared } }. volume.Bind non-nil at line 103 triggers the error.

Common situations: Converting a bind mount to an image mount and leaving the bind block. YAML merge keys importing a bind block into an image entry. Reusing a mount template across types.

Related errors

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/31aeb455aebdff19. Report an issue: GitHub.

Appendix: source

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

			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,
		}
	}
	return result, nil
}

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

View on GitHub (pinned to 4f84911bfe)