missing annotation com.docker.compose.envfile in layer %q

Error message

missing annotation com.docker.compose.envfile in layer %q

What it means

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.

Source

Thrown at pkg/remote/oci.go:258

	f, err := os.OpenFile(filepath.Join(local, file), os.O_RDWR|os.O_CREATE|os.O_APPEND, 0o600)
	if err != nil {
		return err
	}
	defer func() { _ = f.Close() }()
	if _, ok := layer.Annotations["com.docker.compose.file"]; i > 0 && ok {
		_, err := f.Write([]byte("\n---\n"))
		if err != nil {
			return err
		}
	}
	_, err = f.Write(content)
	return err
}

func writeEnvFile(layer spec.Descriptor, local string, content []byte) error {
	envfilePath, ok := layer.Annotations["com.docker.compose.envfile"]
	if !ok {
		return fmt.Errorf("missing annotation com.docker.compose.envfile in layer %q", layer.Digest)
	}
	if err := validatePathInBase(local, envfilePath); err != nil {
		return err
	}
	otherFile, err := os.Create(filepath.Join(local, envfilePath))
	if err != nil {
		return err
	}
	defer func() { _ = otherFile.Close() }()
	_, err = otherFile.Write(content)
	return err
}

var _ loader.ResourceLoader = (*ociRemoteLoader)(nil)

View on GitHub (pinned to ddc4b044b6)

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.

Example fix

# before: env-file layer pushed without annotations
# after: annotate when building the bundle
oras push registry.example.com/bundle:1 \
  --artifact-type application/vnd.docker.compose.project.v1+json \
  .env:application/vnd.docker.compose.envfile.v1+text \
  --annotation "com.docker.compose.envfile=.env"

Defensive patterns

Strategy: validation

Validate before calling

// when publishing, verify every env-file layer carries the annotation
for _, layer := range manifest.Layers {
    if layer.MediaType == composeEnvFileMediaType {
        if _, ok := layer.Annotations["com.docker.compose.envfile"]; !ok {
            return fmt.Errorf("env-file layer %s missing com.docker.compose.envfile annotation", layer.Digest)
        }
    }
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/5c8040356879d5e6. Report an issue: GitHub.