lionsoul2014/ip2region · error · ValueError

invalid structure version {}

Error message

invalid structure version {}

What it means

util.verify() reads the xdb header and only understands structure versions 2.0 (XdbStructure20) and 3.0 (XdbStructure30). Any other version number in the header means the file layout is unknown/incompatible, so verification aborts with ValueError.

Source

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

# ---
# Verify if the current Searcher could be used to search the specified xdb file.
# Why do we need this check ?
# The future features of the xdb impl may cause the current searcher not able to work properly.
# 
# @Note: You Just need to check this ONCE when the service starts
# Or use another process (eg, A command) to check once Just to confirm the suitability.
def verify(handle):
    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. Upgrade the ip2region Python binding to a version that supports the file's structure version
  2. Re-export/re-download an xdb in v2.0 or v3.0 format compatible with your library
  3. Confirm the file is actually an xdb (correct path, not HTML error page or zero-byte download)

Example fix

# before
util.verify_from_file('new_v3_format.xdb')  # old lib only knows v2
# after
pip install -U ip2region  # get a binding supporting the structure version
util.verify_from_file('new_v3_format.xdb')
Defensive patterns

Strategy: validation

Validate before calling

import struct
with open(db_file, 'rb') as f:
    header = f.read(256)
version = struct.unpack('2H', header[0:4])[0]  # per xdb header layout
if version not in (2, 3):
    raise ValueError(f"unsupported xdb structure version {version}; update the library")

Try / catch

try:
    util.verify_from_file(db_file)
except ValueError as e:
    if 'invalid structure version' in str(e):
        raise RuntimeError('xdb format unsupported; upgrade ip2region binding') from e
    raise

Prevention

When it happens

Trigger: Running verify()/verify_from_file() against an xdb whose header version field is neither 2 nor 3 — a future-format file, a non-xdb file whose first bytes parse as a bogus version, or an encrypted/legacy format.

Common situations: Downloading a newer-format xdb (e.g. v4) with an older library; pointing verify at a random/corrupt file; mixing a v3 xdb with an old binding that only knows v2.

Related errors

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