{"record":{"id":"6dbe4965e90c613f","repo":"hyperledger/fabric","slug":"error-seeking-block-file-s-to-startoffset-d","errorCode":null,"errorMessage":"error seeking block file [%s] to startOffset [%d]","messagePattern":"error seeking block file \\[(.+?)\\] to startOffset \\[(.+?)\\]","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/ledger/blkstorage/block_stream.go","lineNumber":64,"sourceCode":"\tfileNum          int\n\tblockStartOffset int64\n\tblockBytesOffset int64\n}\n\n// /////////////////////////////////\n// blockfileStream functions\n// //////////////////////////////////\nfunc newBlockfileStream(rootDir string, fileNum int, startOffset int64) (*blockfileStream, error) {\n\tfilePath := deriveBlockfilePath(rootDir, fileNum)\n\tlogger.Debugf(\"newBlockfileStream(): filePath=[%s], startOffset=[%d]\", filePath, startOffset)\n\tvar file *os.File\n\tvar err error\n\tif file, err = os.OpenFile(filePath, os.O_RDONLY, 0o600); err != nil {\n\t\treturn nil, errors.Wrapf(err, \"error opening block file %s\", filePath)\n\t}\n\tvar newPosition int64\n\tif newPosition, err = file.Seek(startOffset, 0); err != nil {\n\t\treturn nil, errors.Wrapf(err, \"error seeking block file [%s] to startOffset [%d]\", filePath, startOffset)\n\t}\n\tif newPosition != startOffset {\n\t\tpanic(fmt.Sprintf(\"Could not seek block file [%s] to startOffset [%d]. New position = [%d]\",\n\t\t\tfilePath, startOffset, newPosition))\n\t}\n\ts := &blockfileStream{fileNum, file, bufio.NewReader(file), startOffset}\n\treturn s, nil\n}\n\nfunc (s *blockfileStream) nextBlockBytes() ([]byte, error) {\n\tblockBytes, _, err := s.nextBlockBytesAndPlacementInfo()\n\treturn blockBytes, err\n}\n\n// nextBlockBytesAndPlacementInfo returns bytes for the next block\n// along with the offset information in the block file.\n// An error `ErrUnexpectedEndOfBlockfile` is returned if a partial written data is detected\n// which is possible towards the tail of the file if a crash had taken place during appending of a block","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/common/ledger/blkstorage/block_stream.go#L46-L82","documentation":"Wraps the error returned by file.Seek when newBlockfileStream fails to position the blockfile reader at the requested startOffset. This indicates an OS-level seek failure (bad descriptor, I/O error, or negative/invalid offset), not merely a wrong position. If the seek succeeds but lands elsewhere, a panic is raised instead (error 243).","triggerScenarios":"newBlockfileStream(rootDir, fileNum, startOffset) where file.Seek(startOffset, 0) returns an error — e.g. startOffset is negative, the file descriptor is bad, or an underlying I/O error occurs.","commonSituations":"Corrupt checkpoint/index metadata storing a negative or garbage offset; ledger files replaced underneath a running process; disks with failing sectors returning EIO during seek on some filesystems.","solutions":["Inspect the wrapped OS error (%v) to identify EINVAL/EBADF/EIO and address the root cause","Verify the offset source (checkpoint file, blockfilesInfo, or caller-supplied startOffset) is not corrupt","Rebuild ledger state via peer rollback/rebuild or restore from a snapshot if offsets are corrupt","Check storage health (dmesg, SMART) if EIO is reported"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if startOffset < 0 {\n    return fmt.Errorf(\"invalid startOffset %d for file %d\", startOffset, fileNum)\n}","typeGuard":null,"tryCatchPattern":"s, err := newBlockfileStream(rootDir, num, offset)\nif err != nil {\n    logger.Errorf(\"seek failed on blockfile %d@%d: %v\", num, offset, err)\n    return err\n}","preventionTips":["Validate offsets stored in checkpoint/index metadata before use","Keep ledger files on healthy local storage; monitor for EIO","Do not modify ledger files externally while the peer runs"],"tags":["fabric","ledger","filesystem","seek"],"backgroundTag":"io-seek-failed","analyzedSha":"2736b63f8fd5932511d56fe68b7039d15977f7f6","analyzedAt":"2026-09-04T08:52:36.465Z","contentChangedAt":"2026-09-04T08:52:36.465Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}