{"record":{"id":"47acaf936929a8d8","repo":"lionsoul2014/ip2region","slug":"failed-to-fread-from-len","errorCode":null,"errorMessage":"failed to fread from {$len}","messagePattern":"failed to fread from (.+?)","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"binding/php/xdb/Searcher.class.php","lineNumber":563,"sourceCode":"    }\n\n    // read specified bytes from the specified index\n    private function read($offset, $len) {\n        // check the in-memory buffer first\n        if ($this->contentBuff != null) {\n            return substr($this->contentBuff, $offset, $len);\n        }\n\n        // read from the file\n        $r = fseek($this->handle, $offset);\n        if ($r == -1) {\n            throw new Exception(\"failed to fseek to {$offset}\");\n        }\n\n        $this->ioCount++;\n        $buff = fread($this->handle, $len);\n        if ($buff === false) {\n            throw new Exception(\"failed to fread from {$len}\");\n        }\n\n        if (strlen($buff) != $len) {\n            throw new Exception(\"incomplete read: read bytes should be {$len}\");\n        }\n\n        return $buff;\n    }\n\n}\n","sourceCodeStart":545,"sourceCodeEnd":574,"githubUrl":"https://github.com/lionsoul2014/ip2region/blob/c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1/binding/php/xdb/Searcher.class.php#L545-L574","documentation":"After a successful fseek, the searcher reads $len bytes with fread(); fread() returning false means the read itself failed at the OS/PHP level. The library throws to signal that the xdb index could not be read.","triggerScenarios":"search()/read() on a file-backed searcher where fread() returns false — closed or unreadable handle, disk/permission error, or stream in an error state.","commonSituations":"File deleted or permissions changed after the searcher was created; reading from a network mount that dropped; handle exhausted by an earlier error.","solutions":["Re-create the searcher (newWithFileOnly or newWithBuffer) so a fresh, readable handle is used","Check file permissions and that the xdb file still exists and is readable by the PHP process","Use newWithBuffer()/full-buffer mode to read the whole file once and avoid repeated I/O failures during search"],"exampleFix":"// before\n$handle = fopen($dbFile, 'rb'); // unreadable perms\n// after\n$searcher = \\ip2region\\XdbSearcher::newWithBuffer(file_get_contents($dbFile));","handlingStrategy":"try-catch","validationCode":"if (!is_readable($dbFile)) {\n    throw new RuntimeException(\"xdb file not readable: {$dbFile}\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    $region = $searcher->search($ip);\n} catch (\\Exception $e) {\n    if (strpos($e->getMessage(), 'failed to fread') !== false) {\n        $region = null; // log and mark service degraded / reload searcher\n    } else {\n        throw $e;\n    }\n}","preventionTips":["Verify file readability and permissions at startup","Load the xdb fully into memory (buffer mode) for high-traffic services","Watch for external processes replacing/deleting the xdb file and reload on change"],"tags":["php","file-io","fread","io-error"],"backgroundTag":"file-read-failed","analyzedSha":"c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1","analyzedAt":"2026-09-02T16:58:39.988Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}