{"record":{"id":"c99b4ff08d29e91f","repo":"XX-net/XX-Net","slug":"s-file-format-error","errorCode":null,"errorMessage":"%s file format error","messagePattern":"(.+?) file format error","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"code/default/smart_router/local/ip_region.py","lineNumber":54,"sourceCode":"\n    def __init__(self):\n        self.cn = b\"CN\"\n        self.ipdb = self.load_db()\n\n    def load_db(self):\n        if not os.path.isfile(self.cn_ipdb):\n            self.generate_db()\n\n        with open(self.cn_ipdb, 'rb') as f:\n            # 读取 IP 范围数据长度 BE Ulong -> int\n            data_len, = struct.unpack('>L', f.read(4))\n            # 读取索引数据\n            index = f.read(224 * 4)\n            # 读取 IP 范围数据\n            data = f.read(data_len)\n            # 简单验证结束\n            if f.read(3) != b'end':\n                raise ValueError('%s file format error' % self.cn_ipdb)\n            # 读取更新信息\n            self.update = f.read().decode('ascii')\n        # 格式化并缓存索引数据\n        # 使用 struct.unpack 一次性分割数据效率更高\n        # 每 4 字节为一个索引范围 fip：BE short -> int，对应 IP 范围序数\n        self.index = struct.unpack('>' + 'h' * (224 * 2), index)\n        # 每 8 字节对应一段直连 IP 范围和一段非直连 IP 范围\n        self.raw_data = data\n\n    def check_ip(self, ip):\n        ip = utils.to_str(ip)\n        if \":\" in ip:\n            return False\n\n        #转换 IP 为 BE Uint32，实际类型 bytes\n        nip = socket.inet_aton(ip)\n        #确定索引范围\n        index = self.index","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/XX-net/XX-Net/blob/cfa5bc17b67676e467f37ec50766127e0ab5f0aa/code/default/smart_router/local/ip_region.py#L36-L72","documentation":"Raised while loading the China IP database file (cn_ipdb) in the smart router's ip_region module. The loader reads a fixed 224*4-byte index and data_len bytes of IP ranges, then expects the 3-byte trailer b'end'. If that trailer is missing the file is judged corrupt or in an unexpected format and a ValueError('%s file format error') is raised from load_db during __init__.","triggerScenarios":"Instantiating the IpRegion class when data/cn_ipdb.dat (or whatever path self.cn_ipdb points to) is truncated, corrupted, from an incompatible ipdb version, or is an HTML error page saved in place of the real database.","commonSituations":"Interrupted/partial download of the ipdb file, wrong file placed at the configured path, version mismatch between the ipdb data file and the reader code expecting the 'end' marker layout.","solutions":["Re-download the China IP database file so it is complete and matches the expected format","Verify the file size: it must contain 224*4 index bytes + data_len + 3-byte 'end' trailer; replace if truncated","Check self.cn_ipdb path configuration points to the correct data file","If format changed upstream, update the reader in code/default/smart_router/local/ip_region.py to match the new layout"],"exampleFix":"# before\nif f.read(3) != b'end':\n    raise ValueError('%s file format error' % self.cn_ipdb)\n\n# after (self-heal: re-download once before failing)\nif f.read(3) != b'end':\n    try:\n        download_cn_ipdb(self.cn_ipdb)\n        return self.load_db()\n    except Exception:\n        raise ValueError('%s file format error' % self.cn_ipdb)","handlingStrategy":"validation","validationCode":"import os\nEXPECTED_MIN = 224*4 + 3\ndef ipdb_ok(path):\n    if not os.path.isfile(path) or os.path.getsize(path) < EXPECTED_MIN:\n        return False\n    with open(path,'rb') as f:\n        f.seek(-3, os.SEEK_END)\n        return f.read(3) == b'end'","typeGuard":null,"tryCatchPattern":"try:\n    region = IpRegion()\nexcept ValueError as e:\n    if 'file format error' in str(e):\n        re_download_ipdb(); region = IpRegion()\n    else:\n        raise","preventionTips":["Validate the ipdb file (size + 'end' trailer) before constructing IpRegion","Keep the data file out of directories that partial downloads write to","Automatically re-download on format errors instead of crashing"],"tags":["ip-database","file-format","smart-router","data-corruption"],"backgroundTag":"corrupt-data-file","analyzedSha":"cfa5bc17b67676e467f37ec50766127e0ab5f0aa","analyzedAt":"2026-08-27T19:28:28.225Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}