tmpfs options are incompatible with type volume

Error message

tmpfs options are incompatible with type volume

What it means

Returned by handleVolumeToMount (volume.go:47-48) when a Compose service volume is type: volume but also carries a 'tmpfs' sub-options block. tmpfs options (e.g. size) only apply to type: tmpfs mounts; mixing them into a volume mount is rejected during conversion.

Solutions

Remove the 'tmpfs:' sub-key from the volume-type mount.
If tmpfs semantics (in-memory, size-capped) are intended, set type: tmpfs and drop the volume source.
Run 'docker compose config' to confirm the cleaned-up file.

Example fix

# before
volumes:
  - type: volume
    source: data
    target: /data
    tmpfs:
      size: 1000000000

# after
volumes:
  - type: volume
    source: data
    target: /data

Defensive patterns

Strategy: validation

Validate before calling

// Ensure a volume-type mount does not carry tmpfs options.
func validateVolumeMount(v composetypes.ServiceVolumeConfig) error {
    if (v.Type == "volume" || v.Type == "") && v.Tmpfs != nil {
        return errors.New("tmpfs options are incompatible with type volume")
    }
    return nil
}

Type guard

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

Prevention

When changing a mount's type, remove the previous type's option block.
Do not share YAML anchors for option blocks across different mount types.
Use 'docker compose config' to catch mismatches early.

When it happens

Trigger: In docker-compose.yml: { type: volume, source: data, target: /data, tmpfs: { size: 1000000000 } }. volume.Tmpfs non-nil at line 47 triggers the error.

Common situations: Changing a mount's type from tmpfs to volume but leaving the tmpfs options behind. YAML anchors merging a tmpfs block into a volume entry. Copy-paste from a tmpfs example.

Related errors

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

Appendix: source

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

		Target:      volume.Target,
		ReadOnly:    volume.ReadOnly,
		Source:      volume.Source,
		Consistency: mount.Consistency(volume.Consistency),
	}
}

func handleVolumeToMount(
	volume composetypes.ServiceVolumeConfig,
	stackVolumes volumes,
	namespace Namespace,
) (mount.Mount, error) {
	result := createMountFromVolume(volume)

	if volume.Image != nil {
		return mount.Mount{}, errors.New("images options are incompatible with type volume")
	}
	if volume.Tmpfs != nil {
		return mount.Mount{}, errors.New("tmpfs options are incompatible with type volume")
	}
	if volume.Bind != nil {
		return mount.Mount{}, errors.New("bind options are incompatible with type volume")
	}
	if volume.Cluster != nil {
		return mount.Mount{}, errors.New("cluster options are incompatible with type volume")
	}
	// Anonymous volumes
	if volume.Source == "" {
		return result, nil
	}

	stackVolume, exists := stackVolumes[volume.Source]
	if !exists {
		return mount.Mount{}, fmt.Errorf("undefined volume %q", volume.Source)
	}

	result.Source = namespace.Scope(volume.Source)

View on GitHub (pinned to 4f84911bfe)