{"record":{"id":"99852f3e3200c7f6","repo":"golang/go","slug":"cannot-embed-s-s-invalid-name-s","errorCode":null,"errorMessage":"cannot embed %s %s: invalid name %s","messagePattern":"cannot embed (.+?) (.+?): invalid name (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cmd/go/internal/load/pkg.go","lineNumber":2217,"sourceCode":"\t\t\tif info.IsDir() {\n\t\t\t\twhat = \"directory\"\n\t\t\t}\n\n\t\t\t// Check that directories along path do not begin a new module\n\t\t\t// (do not contain a go.mod).\n\t\t\tfor dir := file; len(dir) > len(pkgdir)+1 && !dirOK[dir]; dir = filepath.Dir(dir) {\n\t\t\t\tif _, err := fsys.Stat(filepath.Join(dir, \"go.mod\")); err == nil {\n\t\t\t\t\treturn nil, nil, fmt.Errorf(\"cannot embed %s %s: in different module\", what, rel)\n\t\t\t\t}\n\t\t\t\tif dir != file {\n\t\t\t\t\tif info, err := fsys.Lstat(dir); err == nil && !info.IsDir() {\n\t\t\t\t\t\treturn nil, nil, fmt.Errorf(\"cannot embed %s %s: in non-directory %s\", what, rel, dir[len(pkgdir)+1:])\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tdirOK[dir] = true\n\t\t\t\tif elem := filepath.Base(dir); isBadEmbedName(elem) {\n\t\t\t\t\tif dir == file {\n\t\t\t\t\t\treturn nil, nil, fmt.Errorf(\"cannot embed %s %s: invalid name %s\", what, rel, elem)\n\t\t\t\t\t} else {\n\t\t\t\t\t\treturn nil, nil, fmt.Errorf(\"cannot embed %s %s: in invalid directory %s\", what, rel, elem)\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tswitch {\n\t\t\tdefault:\n\t\t\t\treturn nil, nil, fmt.Errorf(\"cannot embed irregular file %s\", rel)\n\n\t\t\tcase info.Mode().IsRegular():\n\t\t\t\tif have[rel] != pid {\n\t\t\t\t\thave[rel] = pid\n\t\t\t\t\tlist = append(list, rel)\n\t\t\t\t}\n\n\t\t\t// If the embedfollowsymlinks GODEBUG is set to 1, allow the leaf file to be a\n\t\t\t// symlink (#59924). We don't allow directories to be symlinks and have already","sourceCodeStart":2199,"sourceCodeEnd":2235,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/cmd/go/internal/load/pkg.go#L2199-L2235","documentation":"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).","triggerScenarios":"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`.","commonSituations":"Asset files exported from GUI tools with spaces or parentheses; files with emoji or accented characters in the name; macOS metadata files leaking in.","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."],"exampleFix":"// before: assets/Report (final).csv cannot be embedded\n// after: rename to assets/report_final.csv, then\n//go:embed assets","handlingStrategy":"validation","validationCode":"// Reject embed targets whose base name fails cmd/go's isBadEmbedName rule\n// (only [a-zA-Z0-9._-] plus '/' are safe; anything else, including spaces,\n// colons, parens, non-ASCII, is bad).\npackage embedcheck\n\nimport (\n\t\"errors\"\n\t\"path/filepath\"\n\t\"unicode/utf8\"\n)\n\nfunc ValidEmbedFileName(name string) error {\n\tbase := filepath.Base(name)\n\tfor _, r := range base {\n\t\tif r >= utf8.RuneSelf {\n\t\t\treturn errors.New(\"non-ASCII char in embed name: \" + base)\n\t\t}\n\t\tswitch {\n\t\tcase 'a' <= r && r <= 'z', 'A' <= r && r <= 'Z', '0' <= r && r <= '9':\n\t\tcase r == '.', r == '_', r == '-':\n\t\tdefault:\n\t\t\treturn errors.New(\"disallowed char in embed name: \" + base)\n\t\t}\n\t}\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["embed","filesystem","naming","go-embed"],"backgroundTag":null,"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}