{"record":{"id":"c2faec155f223180","repo":"juicedata/juicefs","slug":"failed-to-read-segment-value-err-v-read-len-d","errorCode":null,"errorMessage":"failed to read segment value: err %v, read len %d, expect len %d","messagePattern":"failed to read segment value: err (.+?), read len (.+?), expect len (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/meta/backup.go","lineNumber":364,"sourceCode":"\treturn binary.Size(s.typ) + binary.Size(s.len) + len(data), nil\n}\n\nfunc (s *BakSegment) Unmarshal(r io.Reader) error {\n\tif err := binary.Read(r, binary.BigEndian, &s.typ); err != nil {\n\t\treturn fmt.Errorf(\"failed to read segment type: %v\", err)\n\t}\n\n\tif s.typ == BakEOS {\n\t\treturn errBakEOF\n\t}\n\n\tif err := binary.Read(r, binary.BigEndian, &s.len); err != nil {\n\t\treturn fmt.Errorf(\"failed to read segment %s length: %v\", s, err)\n\t}\n\tdata := make([]byte, s.len)\n\tn, err := r.Read(data)\n\tif err != nil && n != int(s.len) {\n\t\treturn fmt.Errorf(\"failed to read segment value: err %v, read len %d, expect len %d\", err, n, s.len)\n\t}\n\n\tmsg, err := getMessageFromType(int(s.typ))\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to create message by type %d: %w\", s.typ, err)\n\t}\n\tif err = proto.Unmarshal(data, msg); err != nil {\n\t\treturn fmt.Errorf(\"failed to unmarshal segment msg %d: %w\", s.typ, err)\n\t}\n\ts.val = msg\n\treturn nil\n}\n\ntype DumpOption struct {\n\tKeepSecret bool\n\tThreads    int\n\tProgress   func(name string, cnt int)\n}","sourceCodeStart":346,"sourceCodeEnd":382,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/backup.go#L346-L382","documentation":"After reading the segment length, BakSegment.Unmarshal allocates a buffer of s.len bytes and reads the payload with a single r.Read call. This error is thrown when the read fails or returns fewer bytes than s.len, meaning the segment payload is truncated or the stream is unreadable. Note the guard `err != nil && n != int(s.len)` means a short read with nil error is silently accepted (io.Reader contract violation by the source), while any error with an incomplete read produces this message.","triggerScenarios":"Calling ReadFooter on a stream whose segment payload is cut short: backup truncated mid-segment, corrupted file, or an I/O error (device failure, closed handle) during payload read; also a giant/corrupt s.len making the expected length unreachable.","commonSituations":"Metadata backup interrupted by crash or disk-full mid-segment; file transferred incompletely (e.g., partial upload/download); reading a backup over an unreliable mount that returns errors mid-read.","solutions":["Regenerate the backup — a truncated payload means the footer cannot be trusted","Compare the backup file size/checksum with the source to confirm truncation and fix the transfer","Check the health of the storage backing the backup (disk errors, mount stability)","If a custom io.Reader is the source, fix it to fill the buffer or return io.ErrUnexpectedEOF on short reads"],"exampleFix":"// before (caller-side, more robust read)\nn, err := r.Read(data)\n// after (read fully)\nif _, err := io.ReadFull(r, data); err != nil {\n    return fmt.Errorf(\"failed to read segment value: %w\", err)\n}","handlingStrategy":"try-catch","validationCode":"fi, err := os.Stat(backupPath)\nif err != nil { return err } // then compare fi.Size() against bytes already consumed before trusting remaining payload","typeGuard":null,"tryCatchPattern":"if err := seg.Unmarshal(r); err != nil {\n    if strings.Contains(err.Error(), \"failed to read segment value\") {\n        return fmt.Errorf(\"backup payload truncated, regenerate backup: %w\", err)\n    }\n    return err\n}","preventionTips":["Prefer io.ReadFull semantics when supplying readers to Unmarshal","Verify backup integrity (checksum) after transfer before loading","Retry failed transfers instead of loading partially copied files"],"tags":["io","read-failed","truncated-data","short-read","backup"],"backgroundTag":"file-read-failed","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}