{"record":{"id":"c3b9a117a2e19240","repo":"docker/compose","slug":"volume-with-type-image-require-docker-engine-s-or","errorCode":null,"errorMessage":"volume with type=image require Docker Engine %s or later","messagePattern":"volume with type=image require Docker Engine (.+?) or later","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/compose/create.go","lineNumber":986,"sourceCode":"\t\tcase mount.TypeVolume:\n\t\t\tv := findVolumeByTarget(service.Volumes, m.Target)\n\t\t\tvol := findVolumeByName(p.Volumes, m.Source)\n\t\t\tif v != nil && vol != nil {\n\t\t\t\t// Prefer the bind API if no advanced option is used, to preserve backward compatibility\n\t\t\t\tif !volumeRequiresMountAPI(v.Volume) {\n\t\t\t\t\tbinds = append(binds, toBindString(vol.Name, v))\n\t\t\t\t\tcontinue\n\t\t\t\t}\n\t\t\t}\n\t\tcase mount.TypeImage:\n\t\t\t// The daemon validates image mounts against the negotiated API version\n\t\t\t// from the request path, not the server's own max version.\n\t\t\tversion, err := s.RuntimeAPIVersion(ctx)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, nil, err\n\t\t\t}\n\t\t\tif versions.LessThan(version, apiVersion148) {\n\t\t\t\treturn nil, nil, fmt.Errorf(\"volume with type=image require Docker Engine %s or later\", dockerEngineV28)\n\t\t\t}\n\t\t}\n\t\tmounts = append(mounts, m)\n\t}\n\treturn binds, mounts, nil\n}\n\nfunc toBindString(name string, v *types.ServiceVolumeConfig) string {\n\taccess := \"rw\"\n\tif v.ReadOnly {\n\t\taccess = \"ro\"\n\t}\n\toptions := []string{access}\n\tif v.Bind != nil && v.Bind.SELinux != \"\" {\n\t\toptions = append(options, v.Bind.SELinux)\n\t}\n\tif v.Bind != nil && v.Bind.Propagation != \"\" {\n\t\toptions = append(options, v.Bind.Propagation)","sourceCodeStart":968,"sourceCodeEnd":1004,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/compose/create.go#L968-L1004","documentation":"Thrown when a service volume uses the newer 'type: image' mount (mount an image as a volume) but the connected Docker Engine negotiates an API version below 1.48 (Docker Engine < v28). The daemon validates image mounts against the API version negotiated from the request path, so compose pre-checks s.RuntimeAPIVersion(ctx) and refuses early with a clear message instead of an opaque daemon error.","triggerScenarios":"A compose file with a volume entry whose type is 'image' (e.g. {type: image, source: alpine, target: /data}) run against an engine older than 28.0 (API < 1.48), e.g. Docker 27.x, older Docker Desktop, or an outdated remote DOCKER_HOST.","commonSituations":"Upgrading compose CLI but not the engine; CI runners pinned to an old docker engine; remote docker context pointing at an old host; feature was added in Engine 28 so older environments silently lack it.","solutions":["Upgrade Docker Engine to v28 or later (API 1.48+) and reconnect","Verify the negotiated version: docker version --format '{{.Server.APIVersion}}'","If upgrade is impossible, replace the image volume with a named volume plus an init step that copies content from the image","Pin tooling that uses type: image to hosts with engine >= 28"],"exampleFix":"# before\nvolumes:\n  - type: image\n    source: alpine:latest\n    target: /mnt/alpine\n# after (engine < 28)\nvolumes:\n  - mydata:/mnt/data\n# plus: docker run --rm -v mydata:/t alpine sh -c 'cp -r /etc /t'","handlingStrategy":"validation","validationCode":"// Go: check negotiated API version before relying on image volumes\nver, err := cli.ServerAPIVersion(ctx)\nif err != nil { return err }\nif versions.LessThan(ver, \"1.48\") {\n    return fmt.Errorf(\"type=image volumes need Engine >= 28 (API 1.48), got %s\", ver)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin CI/engine images to docker:28+ or newer","Feature-detect API version in tooling that reads compose files","Document engine requirements alongside compose files that use type: image"],"tags":["volumes","mounts","versioning","docker-engine"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}