{"record":{"id":"2643984e2d0e5474","repo":"lionsoul2014/ip2region","slug":"invalid-structure-version","errorCode":null,"errorMessage":"invalid structure version {}","messagePattern":"invalid structure version (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"binding/python/ip2region/util.py","lineNumber":257,"sourceCode":"# ---\n# Verify if the current Searcher could be used to search the specified xdb file.\n# Why do we need this check ?\n# The future features of the xdb impl may cause the current searcher not able to work properly.\n# \n# @Note: You Just need to check this ONCE when the service starts\n# Or use another process (eg, A command) to check once Just to confirm the suitability.\ndef verify(handle):\n    header = load_header(handle)\n\n    # get the runtime ptr bytes\n    runtime_ptr_bytes = 0\n    if header.version == XdbStructure20:\n        runtime_ptr_bytes = 4\n    elif header.version == XdbStructure30:\n        runtime_ptr_bytes = header.runtimePtrBytes\n    else:\n        # Higher versions of the structure are usually incompatible.\n        raise ValueError(\"invalid structure version {}\".format(header.version))\n\n    # 1, confirm the xdb file size\n    # to ensure that the maximum file pointer does not overflow\n    max_file_ptr = (1 << (runtime_ptr_bytes * 8)) - 1\n    __file_bytes = os.stat(handle.fileno()).st_size\n    # print(\"max_file_ptr: {}, file_bytes: {}\".format(max_file_ptr, __file_bytes))\n    if __file_bytes > max_file_ptr:\n        raise Exception(\"xdb file exceeds the maximum supported bytes: {}\".format(max_file_ptr))\n\ndef verify_from_file(db_file: str):\n    handle = io.open(db_file, \"rb\")\n    verify(handle)\n    handle.close()","sourceCodeStart":239,"sourceCodeEnd":270,"githubUrl":"https://github.com/lionsoul2014/ip2region/blob/c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1/binding/python/ip2region/util.py#L239-L270","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade the ip2region Python binding to a version that supports the file's structure version","Re-export/re-download an xdb in v2.0 or v3.0 format compatible with your library","Confirm the file is actually an xdb (correct path, not HTML error page or zero-byte download)"],"exampleFix":"# before\nutil.verify_from_file('new_v3_format.xdb')  # old lib only knows v2\n# after\npip install -U ip2region  # get a binding supporting the structure version\nutil.verify_from_file('new_v3_format.xdb')","handlingStrategy":"validation","validationCode":"import struct\nwith open(db_file, 'rb') as f:\n    header = f.read(256)\nversion = struct.unpack('2H', header[0:4])[0]  # per xdb header layout\nif version not in (2, 3):\n    raise ValueError(f\"unsupported xdb structure version {version}; update the library\")","typeGuard":null,"tryCatchPattern":"try:\n    util.verify_from_file(db_file)\nexcept ValueError as e:\n    if 'invalid structure version' in str(e):\n        raise RuntimeError('xdb format unsupported; upgrade ip2region binding') from e\n    raise","preventionTips":["Pin the xdb file format version your deployment supports","Upgrade the binding before adopting newer xdb exports","Validate files after download and before swapping them into production"],"tags":["python","version-mismatch","xdb","validation"],"backgroundTag":"unsupported-structure-version","analyzedSha":"c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1","analyzedAt":"2026-09-02T16:58:39.988Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}