cannot embed directory %s: contains no embeddable files

Error message

cannot embed directory %s: contains no embeddable files

What it means

After WalkDir completes over an embedded directory (line 2298), if count == 0 the loader rejects it: the directory exists but contains zero embeddable files. Embeddable files are visible (no leading '.'/'_'), have a valid name, are regular, and are inside the same module. An all-excluded directory is treated as an error, not silently empty, so typos in the path do not produce silent empty embeds.

Source

Thrown at src/cmd/go/internal/load/pkg.go:2299

							return filepath.SkipDir
						}
						return nil
					}
					if !d.Type().IsRegular() {
						return nil
					}
					count++
					if have[rel] != pid {
						have[rel] = pid
						list = append(list, rel)
					}
					return nil
				})
				if err != nil {
					return nil, nil, err
				}
				if count == 0 {
					return nil, nil, fmt.Errorf("cannot embed directory %s: contains no embeddable files", rel)
				}
			}
		}

		if len(list) == 0 {
			return nil, nil, fmt.Errorf("no matching files found")
		}
		sort.Strings(list)
		pmap[pattern] = list
	}

	for file := range have {
		files = append(files, file)
	}
	sort.Strings(files)
	return files, pmap, nil
}

View on GitHub (pinned to b6b368adc5)

Solutions

Add at least one regular, non-hidden, validly-named file to the directory.
Rename files you want embedded so they do not start with '.' or '_'.
If the directory is legitimately empty, remove the //go:embed directive for it.

Example fix

// before: //go:empty_dir  containing only .gitkeep
// after: add empty_dir/placeholder.txt, or drop the directive

Defensive patterns

Strategy: validation

Validate before calling

// Confirm an embedded directory has at least one embeddable (visible,
// validly-named, regular) file before building.
package embedcheck

import (
	"errors"
	"os"
)

func EmbedDirHasFiles(dir string) error {
	count := 0
	err := filepath.WalkDir(dir, func(p string, d os.DirEntry, err error) error {
		if err != nil || d.IsDir() {
			return nil
		}
		name := d.Name()
		if name[0] == '.' || name[0] == '_' {
			return nil
		}
		if !d.Type().IsRegular() {
			return nil
		}
		if err := ValidEmbedFileName(name); err != nil {
			return nil // badly-named files are skipped, not counted
		}
		count++
		return nil
	})
	if err != nil {
		return err
	}
	if count == 0 {
		return errors.New("embedded directory " + dir + " has no embeddable files")
	}
	return nil
}

Prevention

Do not point //go:embed at output directories that may be empty in CI.
If a directory is intentionally empty, remove its //go:embed directive.

When it happens

Trigger: //go:embed of a directory whose only entries are hidden ('.'/'_' prefix), badly named, irregular, in a nested module, or non-regular. The directory WalkDir'd is structurally present but yields count 0.

Common situations: Embedding a templates folder that only contains `.gitkeep` or `_partials`; an assets dir where everything was moved into a hidden cache; an empty build output directory.

Related errors

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/e3d043db15716e6c. Report an issue: GitHub.