{"record":{"id":"36fec98665e09352","repo":"lionsoul2014/ip2region","slug":"invalid-structure-version-header-version","errorCode":null,"errorMessage":"invalid structure version ${header.version}","messagePattern":"invalid structure version (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"binding/javascript/util.js","lineNumber":406,"sourceCode":"// --- \n\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.\nexport 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":388,"sourceCodeEnd":422,"githubUrl":"https://github.com/lionsoul2014/ip2region/blob/c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1/binding/javascript/util.js#L388-L422","documentation":"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.","triggerScenarios":"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.","commonSituations":"Mixing a v3 maker-produced file with an old reader, or vice versa; hand-crafted/corrupted headers; passing a random binary file to verifyFromFile.","solutions":["Regenerate or download the xdb file with a supported version (v2.0 or v3.0 structure) matching your ip2region library version.","Upgrade the ip2region binding so it recognizes the newer structure version in the file.","Inspect the header version field to confirm what the file actually declares before debugging further.","Verify the file is a real xdb data file, not an unrelated binary."],"exampleFix":"// before\nverifyFromFile('city.ipv4.xdb'); // built by unsupported maker\n// after\nconst fd = fs.openSync(dbPath, 'r');\nconst header = loadHeader(fd);\nif (header.version !== XdbStructure20 && header.version !== XdbStructure30) {\n  throw new Error(`unsupported xdb: regenerate with maker v2/v3 (got version ${header.version})`);\n}\nverify(fd);","handlingStrategy":"validation","validationCode":"const fd = fs.openSync(dbPath, 'r');\nconst header = loadHeader(fd);\nif (![XdbStructure20, XdbStructure30].includes(header.version))\n  throw new Error(`unsupported xdb version ${header.version}; regenerate with a supported maker`);","typeGuard":null,"tryCatchPattern":"try {\n  verifyFromFile(dbPath);\n} catch (e) {\n  if (String(e.message).startsWith('invalid structure version')) {\n    throw new Error(`${dbPath} uses an unsupported format; upgrade ip2region or rebuild the xdb`);\n  }\n  throw e;\n}","preventionTips":["Pin the maker and binding versions so produced files match the reader.","Check the header version after any xdb update pipeline change.","Only consume xdb files from trusted generator runs."],"tags":["nodejs","versioning","xdb","format"],"backgroundTag":"unsupported-file-version","analyzedSha":"c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1","analyzedAt":"2026-09-02T16:58:39.988Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}