A Go binary's //go:embed templates tree is missing _partials/header.html at runtime. Why, and how do you confirm what was embedded?

## The rule that bit you When a `//go:embed` pattern names a directory, the toolchain embeds the whole subtree rooted there — recursively — **except** that files and directories whose names begin with `.` or `_` are excluded. So: ```go //go:embed templates var templates embed.FS ``` quietly leaves out `templates/_partials/`, `templates/.keep`, and anything beneath a directory whose name starts with one of those characters. The exclusion is not arbitrary. Go's own build system has always treated directories starting with `_` or `.` as invisible to package scanning, so `//go:embed` inherited the convention, and it usefully keeps editor droppings, `.DS_Store` files and version-control metadata out of your binary by default. It becomes a trap the moment your asset tree uses those characters for real content — and `_partials`, `_layouts`, `_includes` are extremely common names in template trees, because several template ecosystems use exactly that convention for non-page fragments. ## Why nothing warned you The build failed to complain because the pattern was not empty: `templates` matched plenty of files. Go only rejects a pattern at compile time when it matches **nothing** — `pattern templates/*.css: no matching files found`. That is a genuinely useful guard for a typo'd or renamed directory, but it cannot help with a partial match, and a partial match is exactly what the dot/underscore rule produces. So the error surfaces far away from its cause: `template.ParseFS` parses the pages but not the fragments and fails on an undefined template, or `templates.ReadFile("templates/_partials/header.html")` returns an `*fs.PathError` wrapping `fs.ErrNotExist`. On a laptop, where someone may still be reading templates from disk in a dev mode, everything works; in the shipped binary it does not. That is the version of this bug that reaches production. ## The fix Prefix the pattern with `all:`: ```go //go:embed all:templates var templates embed.FS ``` `all:` means "embed this subtree including names that start with `.` or `_`". Use it deliberately, because it also stops filtering the junk the default rule was protecting you from — if the directory can accumulate editor or tooling files, keep the asset tree clean, or list the specific subdirectories you want. There is one more wrinkle worth carrying: the exclusion applies to the recursive directory walk, not to a top-level glob match. A pattern like `templates/*` explicitly matches the entries directly inside `templates`, including one named `_partials`, while `templates` alone would not. Deeper levels are still filtered. This asymmetry surprises people, and the practical advice is not to rely on it — say what you mean with `all:`. ## Confirming rather than guessing The honest diagnostic is to look inside the `embed.FS`. It implements `fs.FS`, so `fs.WalkDir` works on it directly, rooted at `"."`: ```go fs.WalkDir(templates, ".", func(path string, d fs.DirEntry, err error) error { if err != nil { return err } if !d.IsDir() { fmt.Println(path) } return nil }) ``` Run that and you are reading the truth about the binary rather than about your working directory. Two good places to put it: - **Behind a debug subcommand or flag**, so someone holding a shipped binary can dump its asset inventory without a rebuild. This is cheap and pays for itself the first time an on-call engineer asks "does this build actually contain the new migration?" - **In a test in the same package** that asserts the expected files exist. This is the version that stops the bug recurring, because the assertion fails the moment somebody adds an underscore-prefixed directory. A test is the right home for it precisely because the check is about the contents of a build artefact, and the test compiles the same package with the same directive. ## Related things that are also silently absent - **Empty directories** are not represented in an `embed.FS` at all; the filesystem holds files, and a directory with no embedded files under it simply is not there. - **Symbolic links and irregular files** are not embedded, and patterns cannot reach outside the package directory — no `..`, no absolute paths — so an asset tree shared between two packages must be embedded by a package that actually contains it, and re-exported. - **Paths keep the pattern's prefix.** `templates/index.html`, not `index.html`. A lookup failure that looks like a missing file is very often a missing prefix instead, and `fs.Sub(templates, "templates")` is the usual way to re-root the FS before handing it to something that expects paths without it. The general lesson for the person on call: for an embedded asset tree, the build's silence is not evidence. The FS is a value you can enumerate, so enumerate it.