What causes "file stat: %w" in lionsoul2014/ip2region?

Verify the file path resolves to an existing, readable regular file before opening

lionsoul2014/ip2region · error

file stat: %w

Error message

file stat: %w

What it means

After determining runtime pointer size (4 bytes for v2, header.RuntimePtrBytes for v3), Verify stats the xdb file and wraps any Stat failure as "file stat". Stat errors usually mean the file handle is bad or the file vanished mid-check.

Source

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

		return fmt.Errorf("loading header: %w", err)
	}

	// get the runtime ptr bytes
	runtimePtrBytes := 0
	switch header.Version {
	case Structure20:
		runtimePtrBytes = 4
	case Structure30:
		runtimePtrBytes = header.RuntimePtrBytes
	default:
		return fmt.Errorf("invalid version: %d", header.Version)
	}

	// 1, confirm the xdb file size.
	// to sure that the MaxFilePointer does no overflow
	stat, err := handle.Stat()
	if err != nil {
		return fmt.Errorf("file stat: %w", err)
	}

	maxFilePtr := (int64(1) << (runtimePtrBytes * 8)) - 1
	if stat.Size() > maxFilePtr {
		return fmt.Errorf("xdb file exceeds the maximum supported bytes: %d", maxFilePtr)
	}

	return nil
}

// VerifyFromFile check Verify for details
func VerifyFromFile(dbFile string) error {
	handle, err := os.OpenFile(dbFile, os.O_RDONLY, 0600)
	if err != nil {
		return fmt.Errorf("open xdb file `%s`: %w", dbFile, err)
	}
	defer handle.Close()

View on GitHub (pinned to c1a1fc7d59)

Solutions

Verify the file path resolves to an existing, readable regular file before opening
Re-open the file if it may have been replaced (path-based reopen rather than stale handle)
Check mount/permissions in containerized environments
Run Verify again after fixing the environment — this is an environmental, not format, error

Example fix

// before
f, _ := os.OpenFile(dbFile, os.O_RDONLY, 0600)
os.Remove(dbFile) // file gone
err := xdb.Verify(f) // file stat: ...
// after
if _, err := os.Stat(dbFile); err != nil { log.Fatalf("xdb missing: %v", err) }
f, _ := os.OpenFile(dbFile, os.O_RDONLY, 0600)
err = xdb.Verify(f)

Defensive patterns

Strategy: retry

Validate before calling

info, err := os.Stat(dbPath)
if err != nil { return fmt.Errorf("xdb stat before verify: %w", err) }
if !info.Mode().IsRegular() { return fmt.Errorf("%s is not a regular file", dbPath) }

Try / catch

var err error
for i := 0; i < 3; i++ {
    f, e := os.OpenFile(dbPath, os.O_RDONLY, 0600)
    if e != nil { err = e; continue }
    err = xdb.Verify(f)
    f.Close()
    if err == nil || !strings.Contains(err.Error(), "file stat") { break }
    time.Sleep(100 * time.Millisecond) // file may be mid-replacement
}

Prevention

Replace xdb files atomically (write temp, rename) so handles never go stale
Check os.Stat success before opening the handle
Avoid deleting files behind open handles during hot reloads
Check mount/read-only/permission issues in containers

When it happens

Trigger: Calling Verify/VerifyFromFile on a file deleted or renamed after opening; permission errors on the path (e.g. traversing a non-searchable directory); passing a handle to a special file that cannot be stat'ed.

Common situations: Hot-reloading xdb files where the replacement removes the old inode while the check runs; containers with read-only or masked mounts; symlink targets missing.

Related errors

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