{"record":{"id":"5dfbc0869039d945","repo":"lionsoul2014/ip2region","slug":"invalid-ip-address-expected","errorCode":null,"errorMessage":"invalid ip address `{}` ({} expected)","messagePattern":"invalid ip address `(.+?)` \\((.+?) expected\\)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"binding/python/ip2region/searcher.py","lineNumber":49,"sourceCode":"    def get_ip_version(self):\n        return self.version\n\n    def get_io_count(self):\n        return self.__io_count\n\n    def search(self, ip: Union[bytes, str]):\n        # check and parse the string ip\n        ip_bytes = None\n        if isinstance(ip, str):\n            ip_bytes = util.parse_ip(ip)\n        elif isinstance(ip, bytes):\n            ip_bytes = ip\n        else:\n            raise ValueError(\"invalid ip address `{}`\".format(ip))\n\n        # ip version check\n        if len(ip_bytes) != self.version.byte_num:\n            raise ValueError(\"invalid ip address `{}` ({} expected)\".format(\n                util.ip_to_string(ip_bytes), self.version.name))\n\n        # reset the global io_count\n        self.__io_count = 0\n\n        # located the segment index block based on the vector index\n        s_ptr, e_ptr, i0, i1 = 0, 0, ip_bytes[0], ip_bytes[1]\n        idx = i0 * util.VectorIndexCols * util.VectorIndexSize + i1 * util.VectorIndexSize\n        if self.vector_index != None:\n            s_ptr = util.le_get_uint32(self.vector_index, idx)\n            e_ptr = util.le_get_uint32(self.vector_index, idx + 4)\n        elif self.c_buffer != None:\n            offset = util.HeaderInfoLength + idx\n            s_ptr = util.le_get_uint32(self.c_buffer, offset)\n            e_ptr = util.le_get_uint32(self.c_buffer, offset + 4)\n        else:\n            buff = self.read(util.HeaderInfoLength + idx, util.VectorIndexSize)\n            s_ptr = util.le_get_uint32(buff, 0)","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/lionsoul2014/ip2region/blob/c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1/binding/python/ip2region/searcher.py#L31-L67","documentation":"search() also validates the IP version: if the parsed bytes' length (4 for IPv4, 16 for IPv6) differs from the xdb structure's byte_num, the address cannot be looked up in this file and ValueError is raised, naming the IP and the expected version.","triggerScenarios":"Searching an IPv6 address (16 bytes) against an IPv4 (v2 structure) xdb, or an IPv4 address against an IPv6/v3 xdb; passing bytes of the wrong length directly.","commonSituations":"App migrated to IPv6 traffic but still ships the old IPv4-only xdb; loading the wrong file for the searcher version; manually constructing bytes with the wrong length.","solutions":["Load an xdb file whose IP version matches your addresses (v3/IPv6-capable file for IPv6 lookups)","Check the address family with util.ip_to_string/ipaddress before searching and route v4/v6 to the right searcher","When passing raw bytes, ensure exactly 4 bytes (v4) or 16 bytes (v6)"],"exampleFix":"# before\nsearcher = Searcher.new_with_file_only(dbfile='ip2region.xdb')  # v4 file\nsearcher.search('::ffff:1.2.3.4')\n# after\nsearcher6 = Searcher.new_with_file_only(dbfile='ip2region_v6.xdb')\nsearcher6.search('::ffff:1.2.3.4')","handlingStrategy":"validation","validationCode":"import ipaddress\ndef pick_searcher(ip: str):\n    version = ipaddress.ip_address(ip).version\n    return searcher_v6 if version == 6 else searcher_v4","typeGuard":"def matches_searcher_version(ip_bytes: bytes, searcher) -> bool:\n    return len(ip_bytes) == searcher.version.byte_num","tryCatchPattern":"try:\n    region = searcher.search(ip)\nexcept ValueError as e:\n    if '{} expected'.format(searcher.version.name) in str(e):\n        region = None  # wrong family for this xdb\n    else:\n        raise","preventionTips":["Detect the xdb file's IP version at load time and tag the searcher","Route v4 and v6 traffic to their matching xdb files","When passing raw bytes, assert len in (4, 16) first"],"tags":["python","ip-address","ipv6","version-mismatch"],"backgroundTag":"invalid-ip-address","analyzedSha":"c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1","analyzedAt":"2026-09-02T16:58:39.988Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}