lionsoul2014/ip2region · error

xdb file exceeds the maximum supported bytes: %d

Error message

xdb file exceeds the maximum supported bytes: %d

What it means

Verify enforces that the xdb file size does not exceed the maximum addressable by the runtime pointer width: 2^(ptrBytes*8)-1 (4 GiB - 1 for 4-byte pointers, larger for v3's wider pointers). A larger file cannot be indexed with the given pointer size, so Verify rejects it.

Source

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

	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()

	return Verify(handle)
}

// LoadHeader load the header info from the specified handle
func LoadHeader(handle io.ReadSeeker) (*Header, error) {

View on GitHub (pinned to c1a1fc7d59)

Solutions

1. Use the v3 (Structure30) format with larger RuntimePtrBytes for data files over 4 GiB
2. Split the data into multiple xdb files (e.g. by region) each within the pointer limit
3. Regenerate the file with the current maker so header.RuntimePtrBytes matches the size
4. If the size looks bogus, verify file integrity — a corrupted header can shrink maxFilePtr

Example fix

// before
// v2 file > 4GiB
err := xdb.Verify(f) // xdb file exceeds the maximum supported bytes: 4294967295
// after
// generate with v3 maker
// ./xdb_maker gen --version=3 region.txt ip.v3.xdb
err := xdb.VerifyFromFile("ip.v3.xdb") // ok (RuntimePtrBytes=8)

header, err := xdb.LoadHeaderFromFile(dbPath)
if err != nil { return err }
stat, err := os.Stat(dbPath)
if err != nil { return err }
ptrBytes := 4
if header.Version == xdb.Structure30 { ptrBytes = int(header.RuntimePtrBytes) }
maxSize := int64(1)<<(ptrBytes*8) - 1
if stat.Size() > maxSize {
    return fmt.Errorf("xdb %d bytes exceeds %d-byte limit for %d-byte pointers", stat.Size(), maxSize, ptrBytes)
}

if err := xdb.VerifyFromFile(dbPath); err != nil {
    if strings.Contains(err.Error(), "exceeds the maximum supported bytes") {
        return fmt.Errorf("use v3 format or split the data: %w", err)
    }
    return err
}

When it happens

Trigger: Verifying an extremely large v2 (Structure20, fixed 4-byte pointers) xdb exceeding ~4 GiB; a v3 file whose header.RuntimePtrBytes is too small for the actual file size; corrupted header reporting a small pointer width.

Common situations: Building oversized custom xdb data sets with the v2 maker; mixing a v3 data file with a header claiming v2 pointer width; concatenated or duplicated files that ballooned past the limit.

Related errors

• xdb file exceeds the maximum supported bytes: {}
• invalid version: %d
• xdb file exceeds the maximum supported bytes: ${maxFilePtr}
• invalid ip address (${version.name} expected)
• invalid structure version `${header.version}`

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