{"record":{"id":"2989347c6926e67d","repo":"golang/go","slug":"cannot-embed-file-s-invalid-name-s","errorCode":null,"errorMessage":"cannot embed file %s: invalid name %s","messagePattern":"cannot embed file (.+?): invalid name (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cmd/go/internal/load/pkg.go","lineNumber":2275,"sourceCode":"\t\t\t\t\tif err != nil {\n\t\t\t\t\t\treturn err\n\t\t\t\t\t}\n\t\t\t\t\trel := filepath.ToSlash(str.TrimFilePathPrefix(path, pkgdir))\n\t\t\t\t\tname := d.Name()\n\t\t\t\t\tif path != file && (isBadEmbedName(name) || ((name[0] == '.' || name[0] == '_') && !all)) {\n\t\t\t\t\t\t// Avoid hidden files that user may not know about.\n\t\t\t\t\t\t// See golang.org/issue/42328.\n\t\t\t\t\t\tif d.IsDir() {\n\t\t\t\t\t\t\treturn fs.SkipDir\n\t\t\t\t\t\t}\n\t\t\t\t\t\t// Ignore hidden files.\n\t\t\t\t\t\tif name[0] == '.' || name[0] == '_' {\n\t\t\t\t\t\t\treturn nil\n\t\t\t\t\t\t}\n\t\t\t\t\t\t// Error on bad embed names.\n\t\t\t\t\t\t// See golang.org/issue/54003.\n\t\t\t\t\t\tif isBadEmbedName(name) {\n\t\t\t\t\t\t\treturn fmt.Errorf(\"cannot embed file %s: invalid name %s\", rel, name)\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn nil\n\t\t\t\t\t}\n\t\t\t\t\tif d.IsDir() {\n\t\t\t\t\t\tif _, err := fsys.Stat(filepath.Join(path, \"go.mod\")); err == nil {\n\t\t\t\t\t\t\treturn filepath.SkipDir\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn nil\n\t\t\t\t\t}\n\t\t\t\t\tif !d.Type().IsRegular() {\n\t\t\t\t\t\treturn nil\n\t\t\t\t\t}\n\t\t\t\t\tcount++\n\t\t\t\t\tif have[rel] != pid {\n\t\t\t\t\t\thave[rel] = pid\n\t\t\t\t\t\tlist = append(list, rel)\n\t\t\t\t\t}\n\t\t\t\t\treturn nil","sourceCodeStart":2257,"sourceCodeEnd":2293,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/cmd/go/internal/load/pkg.go#L2257-L2293","documentation":"Inside WalkDir over an embedded DIRECTORY (line 2260 region), for each non-hidden entry (name not starting with '.' or '_') the loader checks isBadEmbedName. A bad name here is fatal (returns an error from the WalkDir callback) and is reported as 'cannot embed file <rel>: invalid name <name>'. Unlike the single-file case this also fires for entries inside an embedded directory.","triggerScenarios":"//go:embed of a directory that contains a non-hidden file with a space, parenthesis, colon, or non-ASCII character in its name. Hidden files ('.'/'_' prefix) are silently skipped, but a visible badly-named file aborts.","commonSituations":"Dropping a designer's asset folder full of `Icon (2).png`-style names into an embedded dir; CI checking out files with characters that isBadEmbedName rejects; cross-platform filename issues.","solutions":["Rename every visible file in the embedded directory to use only ASCII letters, digits, dot, underscore, hyphen.","Prefix badly-named files with '.' or '_' if they should be skipped rather than embedded (then they are ignored, not embedded).","Narrow the embed to a sanitized subdirectory."],"exampleFix":"// before: //go:embed assets  containing assets/Notes (final).txt\n// after: rename to assets/notes_final.txt","handlingStrategy":"validation","validationCode":"// Scan an embedded directory and fail fast on any VISIBLE file whose\n// name isBadEmbedName would reject (matches the per-file rule of 884).\npackage embedcheck\n\nfunc ScanEmbedDir(dir string) error {\n\tentries, err := os.ReadDir(dir)\n\tif err != nil {\n\t\treturn err\n\t}\n\tfor _, e := range entries {\n\t\tname := e.Name()\n\t\tif name[0] == '.' || name[0] == '_' {\n\t\t\tcontinue // hidden, skipped by go:embed\n\t\t}\n\t\tif err := ValidEmbedFileName(name); err != nil {\n\t\t\treturn errors.New(dir + \"/\" + name + \": \" + err.Error())\n\t\t}\n\t}\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run `go vet ./...` after dropping any new asset into an embedded directory.","Adopt a naming convention for embedded assets (kebab-case ASCII) and enforce it in CI."],"tags":["embed","filesystem","naming","go-embed"],"backgroundTag":null,"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-12T12:31:55.035Z"}