{"record":{"id":"8b58cff92b8d9b9f","repo":"lionsoul2014/ip2region","slug":"invalid-ip-address-this-version-name-expecte","errorCode":null,"errorMessage":"invalid ip address ({$this->version->name} expected)","messagePattern":"invalid ip address \\((.+?) expected\\)","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"binding/php/xdb/Searcher.class.php","lineNumber":483,"sourceCode":"     */\n    public function search($ip) {\n        $ipBytes = Util::parseIP($ip);\n        if ($ipBytes == null) {\n            throw new Exception(\"invalid ip address `{$ip}`\");\n        }\n\n        return $this->searchByBytes($ipBytes);\n    }\n\n    /**\n     * find the region info for the specified binary ip bytes returned by #parseIP.\n     * \n     * @throws Exception\n     */\n    public function searchByBytes($ipBytes) {\n        // ip version check\n        if (strlen($ipBytes) != $this->version->bytes) {\n            throw new Exception(\"invalid ip address ({$this->version->name} expected)\");\n        }\n\n        // reset the global counter\n        $this->ioCount = 0;\n\n        // locate the segment index block based on the vector index\n        $il0 = ord($ipBytes[0]) & 0xFF;\n        $il1 = ord($ipBytes[1]) & 0xFF;\n        $idx = $il0 * VectorIndexCols * VectorIndexSize + $il1 * VectorIndexSize;\n        if ($this->vectorIndex != null) {\n            $sPtr = Util::le_getUint32($this->vectorIndex, $idx);\n            $ePtr = Util::le_getUint32($this->vectorIndex, $idx + 4);\n        } else if ($this->contentBuff != null) {\n            $sPtr = Util::le_getUint32($this->contentBuff, HeaderInfoLength + $idx);\n            $ePtr = Util::le_getUint32($this->contentBuff, HeaderInfoLength + $idx + 4);\n        } else {\n            // read the vector index block\n            $buff = $this->read(HeaderInfoLength + $idx, 8);","sourceCodeStart":465,"sourceCodeEnd":501,"githubUrl":"https://github.com/lionsoul2014/ip2region/blob/c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1/binding/php/xdb/Searcher.class.php#L465-L501","documentation":"The PHP Searcher throws this when the byte length of the IP passed to searchByBytes() does not match the byte count required by the xdb file's IP version (e.g. 4 bytes for IPv4, 16 for IPv6). The library checks the version up front because searching with the wrong IP size would corrupt index lookups.","triggerScenarios":"Calling Searcher::searchByBytes() with a byte string whose strlen() differs from $this->version->bytes — e.g. passing 16-byte IPv6 bytes to a v4-only xdb searcher, or 4-byte bytes to a v6 searcher, or a non-raw binary string.","commonSituations":"Opening an IPv4 xdb file but searching IPv6 addresses (or vice versa); passing a hex/human-readable string like '1.2.3.4' instead of the packed 4-byte form; mixing up a v1 (IPv4) file with the v3 (IPv6-capable) searcher API.","solutions":["Convert the IP string to raw bytes with the library's helper (e.g. inet_pton / util parse) before calling searchByBytes()","Verify the xdb file's IP version matches the addresses you search; load an IPv6-capable (v3) xdb if you need IPv6","Use the higher-level search($ip) entry point which parses and validates the IP string for you"],"exampleFix":"// before\n$searcher->searchByBytes('1.2.3.4');\n// after\n$bytes = inet_pton('1.2.3.4'); // 4 raw bytes for IPv4\n$searcher->searchByBytes($bytes);","handlingStrategy":"validation","validationCode":"$bytes = is_string($ip) ? (filter_var($ip, FILTER_VALIDATE_IP) ? inet_pton($ip) : null) : $ip;\nif ($bytes === null || strlen($bytes) !== $this->version->bytes) {\n    throw new InvalidArgumentException(\"ip does not match {$this->version->name}\");\n}","typeGuard":"function isIpBytesFor(string $bytes, object $version): bool {\n    return strlen($bytes) === $version->bytes;\n}","tryCatchPattern":"try {\n    $region = $searcher->searchByBytes($bytes);\n} catch (\\Exception $e) {\n    if (strpos($e->getMessage(), 'invalid ip address') !== false) {\n        $region = null; // treat as unresolvable input\n    } else {\n        throw $e;\n    }\n}","preventionTips":["Always feed IPs through the library's string search() instead of crafting bytes yourself","Check the xdb file's version once at startup and keep separate searchers for v4/v6","Unit-test with one known IPv4 and one known IPv6 address"],"tags":["php","ip-address","input-validation","ipv6"],"backgroundTag":"invalid-ip-address","analyzedSha":"c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1","analyzedAt":"2026-09-02T16:58:39.988Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}