{"record":{"id":"6d83064309891dff","repo":"lionsoul2014/ip2region","slug":"xdb-file-exceeds-the-maximum-supported-bytes-ma","errorCode":null,"errorMessage":"xdb file exceeds the maximum supported bytes: ${maxFilePtr}","messagePattern":"xdb file exceeds the maximum supported bytes: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"binding/javascript/util.js","lineNumber":414,"sourceCode":"export function verify(fd) {\n    const header = loadHeader(fd);\n\n    // get the runtime ptr bytes\n    let runtimePtrBytes = 0;\n    if (header.version == XdbStructure20) {\n        runtimePtrBytes = 4;\n    } else if (header.version == XdbStructure30) {\n        runtimePtrBytes = header.runtimePtrBytes;\n    } else {\n        throw new Error(`invalid structure version ${header.version}`);\n    }\n\n    // 1, confirm the xdb file size\n    // to ensure that the maximum file pointer does not overflow\n    const maxFilePtr = (1n << BigInt(runtimePtrBytes * 8)) - 1n;\n    const _fileBytes = BigInt(fs.fstatSync(fd).size);\n    if (_fileBytes > maxFilePtr) {\n        throw new Error(`xdb file exceeds the maximum supported bytes: ${maxFilePtr}`);\n    }\n}\n\nexport function verifyFromFile(dbPath) {\n    const fd = fs.openSync(dbPath, \"r\");\n    verify(fd);\n    fs.closeSync(fd);\n}","sourceCodeStart":396,"sourceCodeEnd":422,"githubUrl":"https://github.com/lionsoul2014/ip2region/blob/c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1/binding/javascript/util.js#L396-L422","documentation":"verify() computes the largest file offset representable by the structure's runtime pointer width (2^(runtimePtrBytes*8) - 1: ~4GB for 4-byte v2 pointers, larger for v3). If fstatSync reports the file is bigger than this maximum, index pointers could not address it, so the library refuses the file.","triggerScenarios":"verifyFromFile(path) on an xdb larger than the pointer ceiling — typically a v2 (4-byte pointer) file exceeding 4GiB, or an oversized merged/custom database.","commonSituations":"Appending multiple databases into one huge file; generating an over-large city/IPv6 db with an old maker; misconfigured merge scripts doubling content.","solutions":["Use the v3 (XdbStructure30) structure, whose runtimePtrBytes supports larger files, by regenerating with an up-to-date maker.","Split the data into multiple xdb files and route queries to the right one.","Trim duplicate/redundant content to bring the file under the pointer limit.","Check the actual file size (ls -l / fstat) to confirm it really exceeds the reported maxFilePtr."],"exampleFix":"// before\nverifyFromFile('merged-6gb.xdb'); // v2 pointers cap at 4GiB-1\n// after\nconst size = fs.statSync('merged-6gb.xdb').size;\nif (size > 2 ** 32 - 1) {\n  throw new Error('xdb exceeds v2 4GiB limit; rebuild as v3 or split the file');\n}\nverifyFromFile('merged-6gb.xdb');","handlingStrategy":"validation","validationCode":"const size = fs.statSync(dbPath).size;\nconst maxPtr = (2n ** 32n) - 1n; // v2 worst case; v3 uses header.runtimePtrBytes\nif (BigInt(size) > maxPtr) throw new Error(`${dbPath} (${size}B) exceeds pointer limit`);","typeGuard":null,"tryCatchPattern":"try {\n  verifyFromFile(dbPath);\n} catch (e) {\n  if (String(e.message).includes('exceeds the maximum supported bytes')) {\n    throw new Error('xdb too large for this structure version; rebuild as v3 or split');\n  }\n  throw e;\n}","preventionTips":["Check the file size after building/merging xdb databases.","Prefer the v3 structure for very large datasets.","Keep databases split per region/family rather than one giant merged file."],"tags":["nodejs","file-size","xdb","limits"],"backgroundTag":"file-size-limit-exceeded","analyzedSha":"c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1","analyzedAt":"2026-09-02T16:58:39.988Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}