lionsoul2014/ip2region · error · Error

invalid structure version ${header.version}

Error message

invalid structure version ${header.version}

What it means

verify() validates an open xdb file against its declared structure version. Only XdbStructure20 (4-byte runtime pointers) and XdbStructure30 (header-declared runtimePtrBytes) are supported; any other version byte in the header triggers this Error.

Source

Thrown at binding/javascript/util.js:406

// --- 

// 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.
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. Regenerate or download the xdb file with a supported version (v2.0 or v3.0 structure) matching your ip2region library version.
2. Upgrade the ip2region binding so it recognizes the newer structure version in the file.
3. Inspect the header version field to confirm what the file actually declares before debugging further.
4. Verify the file is a real xdb data file, not an unrelated binary.

Example fix

// before
verifyFromFile('city.ipv4.xdb'); // built by unsupported maker
// after
const fd = fs.openSync(dbPath, 'r');
const header = loadHeader(fd);
if (header.version !== XdbStructure20 && header.version !== XdbStructure30) {
  throw new Error(`unsupported xdb: regenerate with maker v2/v3 (got version ${header.version})`);
}
verify(fd);

const fd = fs.openSync(dbPath, 'r');
const header = loadHeader(fd);
if (![XdbStructure20, XdbStructure30].includes(header.version))
  throw new Error(`unsupported xdb version ${header.version}; regenerate with a supported maker`);

try {
  verifyFromFile(dbPath);
} catch (e) {
  if (String(e.message).startsWith('invalid structure version')) {
    throw new Error(`${dbPath} uses an unsupported format; upgrade ip2region or rebuild the xdb`);
  }
  throw e;
}

When it happens

Trigger: Calling verify(fd) / verifyFromFile(path) on an xdb written by an unsupported maker version or a future format (e.g. a hypothetical v4), or on a non-xdb file whose header bytes are misinterpreted as a version number.

Common situations: Mixing a v3 maker-produced file with an old reader, or vice versa; hand-crafted/corrupted headers; passing a random binary file to verifyFromFile.

Related errors

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

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