lionsoul2014/ip2region · error · Exception

xdb file exceeds the maximum supported bytes: {}

Error message

xdb file exceeds the maximum supported bytes: {}

What it means

verify() computes the maximum file pointer representable with the structure's runtime pointer width (2^(ptr_bytes*8)-1) and rejects xdb files larger than that, because such a file could not be addressed without pointer overflow. It throws a plain Exception with the max supported byte count.

Source

Thrown at binding/python/ip2region/util.py:265

    header = load_header(handle)

    # get the runtime ptr bytes
    runtime_ptr_bytes = 0
    if header.version == XdbStructure20:
        runtime_ptr_bytes = 4
    elif header.version == XdbStructure30:
        runtime_ptr_bytes = header.runtimePtrBytes
    else:
        # Higher versions of the structure are usually incompatible.
        raise ValueError("invalid structure version {}".format(header.version))

    # 1, confirm the xdb file size
    # to ensure that the maximum file pointer does not overflow
    max_file_ptr = (1 << (runtime_ptr_bytes * 8)) - 1
    __file_bytes = os.stat(handle.fileno()).st_size
    # print("max_file_ptr: {}, file_bytes: {}".format(max_file_ptr, __file_bytes))
    if __file_bytes > max_file_ptr:
        raise Exception("xdb file exceeds the maximum supported bytes: {}".format(max_file_ptr))

def verify_from_file(db_file: str):
    handle = io.open(db_file, "rb")
    verify(handle)
    handle.close()

View on GitHub (pinned to c1a1fc7d59)

Solutions

  1. Use the v3.0 xdb structure (which carries larger runtime pointer widths) for databases exceeding 4 GiB
  2. Re-generate/re-download the xdb so the header's runtimePtrBytes matches the actual file size
  3. If the header is suspect, first check the file size manually and confirm the header bytes are not corrupted

Example fix

# before
util.verify_from_file('huge_v2.xdb')  # > 4GiB, v2 32-bit pointers
# after
# regenerate in v3 format, then:
util.verify_from_file('huge_v3.xdb')
Defensive patterns

Strategy: validation

Validate before calling

import os
size = os.stat(db_file).st_size
if size > (1 << 32) - 1:
    raise ValueError("xdb too large for 32-bit-pointer v2 structure; use v3")

Try / catch

try:
    util.verify_from_file(db_file)
except Exception as e:
    if 'exceeds the maximum supported bytes' in str(e):
        raise RuntimeError('use a v3 xdb structure for files this large') from e
    raise

Prevention

When it happens

Trigger: verify()/verify_from_file() on an xdb whose file size exceeds the pointer ceiling — only realistically for 32-bit-pointer (v2) files larger than ~4 GiB, or when the header's runtimePtrBytes is unexpectedly small.

Common situations: Huge merged/aggregate xdb files in v2 format; corrupted header reporting tiny runtimePtrBytes so even a normal file 'exceeds' the limit.

Related errors

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