lionsoul2014/ip2region · error

failed to load header from `%s`: %s

Error message

failed to load header from `%s`: %s

What it means

Go CLI helper: xdb.LoadHeader could not read/parse the 64-byte header from the opened xdb file (short read or invalid header fields); wrapped as %s with the underlying error text.

Source

Thrown at binding/golang/main.go:94

	handle, err := os.OpenFile(dbPath, os.O_RDONLY, 0600)
	if err != nil {
		return nil, fmt.Errorf("open xdb file `%s`: %w", dbPath, err)
	}

	defer handle.Close()

	// verify the xdb file
	// @Note: do NOT call it every time you create a searcher since this will slow down the search response.
	// @see the util.Verify function for details.
	err = xdb.Verify(handle)
	if err != nil {
		return nil, fmt.Errorf("xdb verify: %w", err)
	}

	// auto-detect the ip version from the xdb header
	header, err := xdb.LoadHeader(handle)
	if err != nil {
		return nil, fmt.Errorf("failed to load header from `%s`: %s", dbPath, err)
	}

	version, err := xdb.VersionFromHeader(header)
	if err != nil {
		return nil, fmt.Errorf("failed to detect IP version from `%s`: %s", dbPath, err)
	}

	switch cachePolicy {
	case "nil", "file":
		return xdb.NewWithFileOnly(version, dbPath)
	case "vectorIndex":
		vIndex, err := xdb.LoadVectorIndexFromFile(dbPath)
		if err != nil {
			return nil, fmt.Errorf("failed to load vector index from `%s`: %w", dbPath, err)
		}

		return xdb.NewWithVectorIndex(version, dbPath, vIndex)
	case "content":

View on GitHub (pinned to c1a1fc7d59)

Solutions

1. Confirm the file is a genuine xdb database of at least header size
2. Re-download the file to rule out truncation
3. Check disk/read errors on the storage holding the db

When it happens

Trigger: Thrown at binding/golang/main.go:94 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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