What causes "failed to read embedded file `%s`: %w" in lionsoul2014/ip2region?

Verify the path passed to LoadContentFromFS exactly matches the //go:embed pattern and its location relative to the Go package directory

lionsoul2014/ip2region · error

failed to read embedded file `%s`: %w

Error message

failed to read embedded file `%s`: %w

What it means

LoadContentFromFS loads an xdb file embedded in the Go binary via go:embed by reading it with io.ReadAll. This error wraps any failure of that read (including the initial os.Open reported through the same wrapping style) so the underlying cause (missing embedded path, permission denied, I/O error) is preserved with %w. It indicates the embedded xdb content could not be materialized into memory.

Source

Thrown at binding/golang/xdb/util.go:307

	if err != nil {
		return nil, err
	}

	return cBuff, nil
}

// LoadContentFromFS load the whole xdb binary from embed.FS
func LoadContentFromFS(fs embed.FS, filePath string) ([]byte, error) {
	file, err := fs.Open(filePath)
	if err != nil {
		return nil, fmt.Errorf("failed to open embedded file `%s`: %w", filePath, err)
	}
	defer file.Close()

	var cBuff []byte
	cBuff, err = io.ReadAll(file)
	if err != nil {
		return nil, fmt.Errorf("failed to read embedded file `%s`: %w", filePath, err)
	}

	return cBuff, nil
}

View on GitHub (pinned to c1a1fc7d59)

Solutions

Verify the path passed to LoadContentFromFS exactly matches the //go:embed pattern and its location relative to the Go package directory
Ensure the xdb file exists in the module and is covered by a //go:embed directive in the same package
Print/log the wrapped error's Unwrap() to identify the root cause (e.g. file not found vs permission)
If loading from an external file at runtime instead, use LoadContentFromFile rather than the FS variant

Example fix

// before
content, err := xdb.LoadContentFromFS("ip.v6.xdb") // file not embedded
// after
//go:embed data/ip.v6.xdb
var xdbFS embed.FS
content, err := xdb.LoadContentFromFS("data/ip.v6.xdb")

Defensive patterns

Strategy: try-catch

Validate before calling

// verify embed coverage before calling
pat := filepath.ToSlash(filePath)
if _, err := embeddedFS.Open(pat); err != nil { return fmt.Errorf("not embedded: %w", err) }

Type guard

func isEmbedded(fsys fs.FS, path string) bool { _, err := fs.Stat(fsys, path); return err == nil }

Try / catch

content, err := xdb.LoadContentFromFS(path)
if err != nil {
    var pe *fs.PathError
    if errors.As(err, &pe) { log.Fatalf("embed path %s: %v", pe.Path, pe.Err) }
    return err
}

Prevention

Keep //go:embed directives adjacent to the code that loads the FS
Use embed.FS listing (fs.WalkDir) in a unit test to assert the xdb is present
Avoid leading '/' and '..' in embed paths
Add a startup smoke test that loads content once and fails fast

When it happens

Trigger: Calling LoadContentFromFS with a file path that was not embedded via //go:embed, an incorrect relative path (embed paths must not start with / or contain ..), or an I/O/read error while reading the opened embedded file.

Common situations: Renaming or moving an .xdb file after the embed directive was written, forgetting the //go:embed annotation so the FS is empty, typo in the path passed to LoadContentFromFS, or running from a context where the embedded FS was populated with a subdirectory prefix.

Related errors

AI-assisted analysis of lionsoul2014/ip2region@c1a1fc7d59 (2026-09-02). Data as JSON: /api/errors/1232716e8ee7539d. Report an issue: GitHub.