{"record":{"id":"5c8040356879d5e6","repo":"docker/compose","slug":"missing-annotation-com-docker-compose-envfile-in-l","errorCode":null,"errorMessage":"missing annotation com.docker.compose.envfile in layer %q","messagePattern":"missing annotation com\\.docker\\.compose\\.envfile in layer %q","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/remote/oci.go","lineNumber":258,"sourceCode":"\tf, err := os.OpenFile(filepath.Join(local, file), os.O_RDWR|os.O_CREATE|os.O_APPEND, 0o600)\n\tif err != nil {\n\t\treturn err\n\t}\n\tdefer func() { _ = f.Close() }()\n\tif _, ok := layer.Annotations[\"com.docker.compose.file\"]; i > 0 && ok {\n\t\t_, err := f.Write([]byte(\"\\n---\\n\"))\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\t_, err = f.Write(content)\n\treturn err\n}\n\nfunc writeEnvFile(layer spec.Descriptor, local string, content []byte) error {\n\tenvfilePath, ok := layer.Annotations[\"com.docker.compose.envfile\"]\n\tif !ok {\n\t\treturn fmt.Errorf(\"missing annotation com.docker.compose.envfile in layer %q\", layer.Digest)\n\t}\n\tif err := validatePathInBase(local, envfilePath); err != nil {\n\t\treturn err\n\t}\n\totherFile, err := os.Create(filepath.Join(local, envfilePath))\n\tif err != nil {\n\t\treturn err\n\t}\n\tdefer func() { _ = otherFile.Close() }()\n\t_, err = otherFile.Write(content)\n\treturn err\n}\n\nvar _ loader.ResourceLoader = (*ociRemoteLoader)(nil)\n","sourceCodeStart":240,"sourceCodeEnd":273,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/remote/oci.go#L240-L273","documentation":"When a manifest layer has the env-file media type, writeEnvFile needs to know the destination filename, which is carried in the layer annotation com.docker.compose.envfile. If that annotation is absent, there is no safe place to write the blob, so the extraction fails naming the layer digest. This guards bundle structure integrity, not user input.","triggerScenarios":"pullComposeFiles encountering a layer whose media type is the compose env-file type but whose Annotations map lacks the com.docker.compose.envfile key. Happens with hand-crafted or third-party-built bundles, or bundles built by an older compose that did not annotate env-file layers.","commonSituations":"Assembling OCI bundles manually with crane/oras/cnab-to-oci and forgetting the annotation; mixing layers from different bundle versions; a publisher's CI stripping annotations during image copy.","solutions":["Rebuild the bundle with `docker compose push` from a current compose version — it sets the annotation on env-file layers automatically.","If you build bundles yourself, add the annotation to every env-file layer: annotation com.docker.compose.envfile = relative path inside the bundle (e.g. .env).","Verify with `docker buildx imagetools inspect <ref> --raw` that each env-file layer includes the annotation before distributing."],"exampleFix":"# before: env-file layer pushed without annotations\n# after: annotate when building the bundle\noras push registry.example.com/bundle:1 \\\n  --artifact-type application/vnd.docker.compose.project.v1+json \\\n  .env:application/vnd.docker.compose.envfile.v1+text \\\n  --annotation \"com.docker.compose.envfile=.env\"","handlingStrategy":"validation","validationCode":"// when publishing, verify every env-file layer carries the annotation\nfor _, layer := range manifest.Layers {\n    if layer.MediaType == composeEnvFileMediaType {\n        if _, ok := layer.Annotations[\"com.docker.compose.envfile\"]; !ok {\n            return fmt.Errorf(\"env-file layer %s missing com.docker.compose.envfile annotation\", layer.Digest)\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always annotate env-file layers with com.docker.compose.envfile = relative path when building bundles.","Prefer `docker compose push` over manual assembly so annotations are set correctly.","Add a CI validation step on published bundles checking required layer annotations."],"tags":["go","docker-compose","oci","bundle-format","validation"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}