Go version

go version go1.24.3 windows/amd64, which I just downloaded today from your website https://go.dev/dl/

Output of go env in your module/workspace:

irrelevant

What did you do?

//go:embed README.md
var readme string

gets the error message go:embed only allowed in Go files that import "embed"

Adding import "embed" or import ( "embed" ) to the file gets you the error "embed" imported and not used. Instead, you have to import _ "embed". So that's what the error message should tell you to do. (It also works if you use embed, the real package, presumably, but the user isn't doing that or the user wouldn't have seen the first error message in the first place!)

What did you see happen?

Cryptic error messages that won't make sense to anyone not already intimately familiar with go's magic import requirement for //go:embed.

What did you expect to see?

Perhaps extend the error message to be go:embed only allowed in Go files that import "embed"; try import _ "embed". Or count the hot comment as a usage for the purposes of the unused import logic.