lionsoul2014/ip2region · error · Error

xdb file exceeds the maximum supported bytes: ${maxFilePtr}

Error message

xdb file exceeds the maximum supported bytes: ${maxFilePtr}

What it means

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.

Source

Thrown at binding/javascript/util.js:414

export function verify(fd) {
    const header = loadHeader(fd);

    // get the runtime ptr bytes
    let runtimePtrBytes = 0;
    if (header.version == XdbStructure20) {
        runtimePtrBytes = 4;
    } else if (header.version == XdbStructure30) {
        runtimePtrBytes = header.runtimePtrBytes;
    } else {
        throw new Error(`invalid structure version ${header.version}`);
    }

    // 1, confirm the xdb file size
    // to ensure that the maximum file pointer does not overflow
    const maxFilePtr = (1n << BigInt(runtimePtrBytes * 8)) - 1n;
    const _fileBytes = BigInt(fs.fstatSync(fd).size);
    if (_fileBytes > maxFilePtr) {
        throw new Error(`xdb file exceeds the maximum supported bytes: ${maxFilePtr}`);
    }
}

export function verifyFromFile(dbPath) {
    const fd = fs.openSync(dbPath, "r");
    verify(fd);
    fs.closeSync(fd);
}

View on GitHub (pinned to c1a1fc7d59)

Solutions

1. Use the v3 (XdbStructure30) structure, whose runtimePtrBytes supports larger files, by regenerating with an up-to-date maker.
2. Split the data into multiple xdb files and route queries to the right one.
3. Trim duplicate/redundant content to bring the file under the pointer limit.
4. Check the actual file size (ls -l / fstat) to confirm it really exceeds the reported maxFilePtr.

Example fix

// before
verifyFromFile('merged-6gb.xdb'); // v2 pointers cap at 4GiB-1
// after
const size = fs.statSync('merged-6gb.xdb').size;
if (size > 2 ** 32 - 1) {
  throw new Error('xdb exceeds v2 4GiB limit; rebuild as v3 or split the file');
}
verifyFromFile('merged-6gb.xdb');

const size = fs.statSync(dbPath).size;
const maxPtr = (2n ** 32n) - 1n; // v2 worst case; v3 uses header.runtimePtrBytes
if (BigInt(size) > maxPtr) throw new Error(`${dbPath} (${size}B) exceeds pointer limit`);

try {
  verifyFromFile(dbPath);
} catch (e) {
  if (String(e.message).includes('exceeds the maximum supported bytes')) {
    throw new Error('xdb too large for this structure version; rebuild as v3 or split');
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: Appending multiple databases into one huge file; generating an over-large city/IPv6 db with an old maker; misconfigured merge scripts doubling content.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

• incomplete read (${rBytes} read, ${header.HeaderInfoLength}
• invalid structure version ${header.version}
• xdb file exceeds the maximum supported bytes: {}
• invalid bytes ip, not a Buffer
• invalid bytes ip with length not 4 or 16

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