{"record":{"id":"4f197b50bbd9780f","repo":"lionsoul2014/ip2region","slug":"xdb-file-exceeds-the-maximum-supported-bytes","errorCode":null,"errorMessage":"xdb file exceeds the maximum supported bytes: {}","messagePattern":"xdb file exceeds the maximum supported bytes: (.+?)","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"binding/python/ip2region/util.py","lineNumber":265,"sourceCode":"    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":247,"sourceCodeEnd":270,"githubUrl":"https://github.com/lionsoul2014/ip2region/blob/c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1/binding/python/ip2region/util.py#L247-L270","documentation":"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.","triggerScenarios":"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.","commonSituations":"Huge merged/aggregate xdb files in v2 format; corrupted header reporting tiny runtimePtrBytes so even a normal file 'exceeds' the limit.","solutions":["Use the v3.0 xdb structure (which carries larger runtime pointer widths) for databases exceeding 4 GiB","Re-generate/re-download the xdb so the header's runtimePtrBytes matches the actual file size","If the header is suspect, first check the file size manually and confirm the header bytes are not corrupted"],"exampleFix":"# before\nutil.verify_from_file('huge_v2.xdb')  # > 4GiB, v2 32-bit pointers\n# after\n# regenerate in v3 format, then:\nutil.verify_from_file('huge_v3.xdb')","handlingStrategy":"validation","validationCode":"import os\nsize = os.stat(db_file).st_size\nif size > (1 << 32) - 1:\n    raise ValueError(\"xdb too large for 32-bit-pointer v2 structure; use v3\")","typeGuard":null,"tryCatchPattern":"try:\n    util.verify_from_file(db_file)\nexcept Exception as e:\n    if 'exceeds the maximum supported bytes' in str(e):\n        raise RuntimeError('use a v3 xdb structure for files this large') from e\n    raise","preventionTips":["Check xdb file size against the structure's pointer width before deploying","Use the v3 structure for very large databases","Verify header runtimePtrBytes after any xdb regeneration"],"tags":["python","file-size","xdb","limit-exceeded"],"backgroundTag":"xdb-file-too-large","analyzedSha":"c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1","analyzedAt":"2026-09-02T16:58:39.988Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}