tmpfs options are incompatible with type image

Error message

tmpfs options are incompatible with type image

What it means

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

Solutions

Remove the 'tmpfs:' sub-key from the image-type mount.
If in-memory size-capped semantics are intended, use type: tmpfs (and drop the image source).
Validate with 'docker compose config'.

Example fix

# before
volumes:
  - type: image
    source: myimg:latest
    target: /app
    tmpfs:
      size: 1000000000

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

Defensive patterns

Strategy: validation

Validate before calling

// Ensure an image-type mount does not carry tmpfs options.
func validateImageMount(v composetypes.ServiceVolumeConfig) error {
    if v.Type == "image" && v.Tmpfs != nil {
        return errors.New("tmpfs 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

tmpfs size options only apply to type: tmpfs; remove them from image mounts.
Avoid generic mount templates that emit all option blocks regardless of type.
Validate compose files with 'docker compose config' in CI.

When it happens

Trigger: In docker-compose.yml: { type: image, source: myimg:latest, target: /app, tmpfs: { size: 1000000000 } }. volume.Tmpfs non-nil at line 106 triggers the error.

Common situations: Switching a tmpfs mount to an image mount and leaving the tmpfs options. YAML anchors merging a tmpfs block into an image entry. Reusing a generic mount template that always emits tmpfs.

Related errors

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

Appendix: source

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

	}

	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)

	if volume.Source == "" {
		return mount.Mount{}, errors.New("invalid bind source, source cannot be empty")
	}

View on GitHub (pinned to 4f84911bfe)