Go "//go:embed: no matching files found" - Fix Embeds in CI

By Kaveh Alemi·Latchkey

The //go:embed directive bakes files into the binary at build time. It fails when the pattern matches nothing - an asset that was not committed, a path outside the package directory, or a missing import "embed" - so the build cannot find what it was told to embed.

What this error means

A build fails with pattern <glob>: no matching files found, //go:embed only allowed in Go files that import "embed", or cannot embed directory ... contains no embeddable files. It often appears in CI where a generated or gitignored asset is absent.

go build output

./assets.go:8:12: pattern static/*: no matching files found
# or:
./assets.go:8:12: //go:embed only allowed in Go files that import "embed"

Diagnose it: toolchain, tags, or platform?

Go build failures that only appear in CI usually come from a different toolchain version, different build tags, or cross-compilation defaults that differ from your machine.

Terminal

go version
go env GOOS GOARCH CGO_ENABLED GOFLAGS GOTOOLCHAIN

# build exactly what CI builds, verbosely
go build -v ./... 2>&1 | tail -40

# CGO is the usual difference: on by default locally, often off in a slim CI image
CGO_ENABLED=0 go build ./...

Common causes

The embedded asset is not present at build time

A file matched by the pattern was gitignored, generated by a step that did not run, or lives outside the package directory - so CI has nothing to embed.

Missing import "embed"

Using //go:embed requires importing the embed package (even as _ "embed" for a string/[]byte target); without it the directive is rejected.

Pattern reaching outside the package directory

//go:embed cannot match .. paths or files outside the directory of the Go file; such patterns find nothing.

How to fix it

Commit the asset and import embed

Ensure the file exists in the repo and the package imports embed.

import _ "embed"

//go:embed static/index.html
var indexHTML string

Generate embedded assets before building

If assets are produced by a step, run it before go build so the files exist.

.github/workflows/ci.yml

npm run build           # produces ./static/*
go build ./...          # embed now finds the files

Keep embed patterns inside the package directory

Move embedded assets under the package directory (no .. paths).
Use all: prefix to include files the default rules skip (dotfiles, _-prefixed).
Confirm the glob matches with ls before building.

How to prevent it

Commit embedded assets, or generate them before go build in CI.
Import embed in any file using //go:embed.
Keep embed patterns within the package directory.

Frequently asked questions

What causes Go "//go:embed: no matching files found"?

There are 3 common causes: the embedded asset is not present at build time, missing import "embed", and pattern reaching outside the package directory. A file matched by the pattern was gitignored, generated by a step that did not run, or lives outside the package directory - so CI has nothing to embed.

How do I fix Go "//go:embed: no matching files found"?

There are 3 fixes depending on which cause you have: commit the asset and import embed, generate embedded assets before building, and keep embed patterns inside the package directory. Work through them in order, since the first is the most common.

What does Go "//go:embed: no matching files found" actually mean?

A build fails with pattern <glob>: no matching files found, //go:embed only allowed in Go files that import "embed", or cannot embed directory ...

How do I stop Go "//go:embed: no matching files found" happening again?

Commit embedded assets, or generate them before go build in CI. The prevention section lists 3 changes that keep it from recurring.