What causes "cannot embed %s %s: invalid name %s" in golang/go?

Rename the embedded file to use only ASCII letters, digits, dot, underscore, hyphen, and slash.

cannot embed %s %s: invalid name %s

Error message

cannot embed %s %s: invalid name %s

What it means

At line 2215, after marking an ancestor dir OK, the loader checks isBadEmbedName on the base name of the current path element. When the offending element is the embed target itself (dir == file), the file's own name is invalid for embedding. isBadEmbedName rejects names containing characters disallowed in embedded file paths (roughly anything outside [a-zA-Z0-9._/-] and a few others, plus bad UTF-8).

Source

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

			if info.IsDir() {
				what = "directory"
			}

			// Check that directories along path do not begin a new module
			// (do not contain a go.mod).
			for dir := file; len(dir) > len(pkgdir)+1 && !dirOK[dir]; dir = filepath.Dir(dir) {
				if _, err := fsys.Stat(filepath.Join(dir, "go.mod")); err == nil {
					return nil, nil, fmt.Errorf("cannot embed %s %s: in different module", what, rel)
				}
				if dir != file {
					if info, err := fsys.Lstat(dir); err == nil && !info.IsDir() {
						return nil, nil, fmt.Errorf("cannot embed %s %s: in non-directory %s", what, rel, dir[len(pkgdir)+1:])
					}
				}
				dirOK[dir] = true
				if elem := filepath.Base(dir); isBadEmbedName(elem) {
					if dir == file {
						return nil, nil, fmt.Errorf("cannot embed %s %s: invalid name %s", what, rel, elem)
					} else {
						return nil, nil, fmt.Errorf("cannot embed %s %s: in invalid directory %s", what, rel, elem)
					}
				}
			}

			switch {
			default:
				return nil, nil, fmt.Errorf("cannot embed irregular file %s", rel)

			case info.Mode().IsRegular():
				if have[rel] != pid {
					have[rel] = pid
					list = append(list, rel)
				}

			// If the embedfollowsymlinks GODEBUG is set to 1, allow the leaf file to be a
			// symlink (#59924). We don't allow directories to be symlinks and have already

View on GitHub (pinned to b6b368adc5)

Solutions

Rename the embedded file to use only ASCII letters, digits, dot, underscore, hyphen, and slash.
If the file lives in an embedded directory, the same rule applies — rename it before go build.
Avoid embedding directories that may accumulate badly-named files; pin a known-good asset folder.

Example fix

// before: assets/Report (final).csv cannot be embedded
// after: rename to assets/report_final.csv, then
//go:embed assets

Defensive patterns

Strategy: validation

Validate before calling

// Reject embed targets whose base name fails cmd/go's isBadEmbedName rule
// (only [a-zA-Z0-9._-] plus '/' are safe; anything else, including spaces,
// colons, parens, non-ASCII, is bad).
package embedcheck

import (
	"errors"
	"path/filepath"
	"unicode/utf8"
)

func ValidEmbedFileName(name string) error {
	base := filepath.Base(name)
	for _, r := range base {
		if r >= utf8.RuneSelf {
			return errors.New("non-ASCII char in embed name: " + base)
		}
		switch {
		case 'a' <= r && r <= 'z', 'A' <= r && r <= 'Z', '0' <= r && r <= '9':
		case r == '.', r == '_', r == '-':
		default:
			return errors.New("disallowed char in embed name: " + base)
		}
	}
	return nil
}

Prevention

Standardize asset filenames to ASCII letters, digits, '.', '_', '-' before adding them to a package.
Add a pre-commit hook (or `go vet`) that fails when an embedded file has a space or parenthesis in its name.

When it happens

Trigger: Embedding a file whose name contains a space, colon, parenthesis, or non-ASCII character that isBadEmbedName flags; e.g. `//go:embed data` where the match is `data/Report (final).csv`.

Common situations: Asset files exported from GUI tools with spaces or parentheses; files with emoji or accented characters in the name; macOS metadata files leaking in.

Related errors

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