{"record":{"id":"122c7be38a19828b","repo":"juicedata/juicefs","slug":"failed-to-read-segment-w","errorCode":null,"errorMessage":"failed to read segment: %w","messagePattern":"failed to read segment: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/load.go","lineNumber":326,"sourceCode":"\tfor _, v := range data {\n\t\tfmt.Printf(\"%-10s| %-10s|\", v[0], v[1])\n\t\tif withOffset {\n\t\t\tfmt.Printf(\" %-10s\", v[2])\n\t\t}\n\t\tfmt.Println()\n\t}\n\treturn nil\n}\n\nfunc showBakDetail(ctx *cli.Context, fp *os.File, offset int64) error {\n\tbak := &meta.BakFormat{}\n\tif _, err := fp.Seek(offset, io.SeekStart); err != nil {\n\t\treturn err\n\t}\n\n\tseg, err := bak.ReadSegment(fp)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to read segment: %w\", err)\n\t}\n\n\tfmt.Printf(\"Segment: %s\\n\", seg.Name())\n\tfmt.Printf(\"Value: %s\\n\", seg)\n\treturn nil\n}\n","sourceCodeStart":308,"sourceCodeEnd":333,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/cmd/load.go#L308-L333","documentation":"`showBakDetail` seeks to a given offset in the backup file and reads one metadata segment via meta.BakFormat.ReadSegment(fp), which decodes a length-prefixed protobuf message. If reading/decoding fails — bad offset, corrupt data, truncated file — the error is wrapped as `failed to read segment: <error>`.","triggerScenarios":"`statBak` with an --offset that does not point at a valid segment boundary (wrong offset, offset from a different backup file), or reading a truncated/corrupted backup where the segment bytes are incomplete or fail protobuf decoding.","commonSituations":"Reusing offsets recorded from another backup version; offset past end-of-file or into the footer; interrupted download leaving partial segment bytes; hand-edited backups.","solutions":["Use the exact offsets printed by the backup summary (`showBakSummary` lists segment names with offsets) from the same file","Verify offset is within the data region, not in the footer or past EOF","Re-download/re-create the backup if bytes are missing (compare checksums/size)","Upgrade the client if the backup was written by a newer JuiceFS version"],"exampleFix":"// before\njuicefs load --stat --offset 999999 meta.sqlite3 backup.json   # guess\n// after\njuicefs load --stat meta.sqlite3 backup.json   # read listed offsets first, then use one exactly","handlingStrategy":"validation","validationCode":"fi, _ := fp.Stat()\nif offset <= 0 || offset >= fi.Size() {\n    return fmt.Errorf(\"offset %d out of data range (size %d)\", offset, fi.Size())\n}","typeGuard":null,"tryCatchPattern":"if err := showDetail(fp, offset); err != nil {\n    if strings.Contains(err.Error(), \"failed to read segment\") {\n        log.Fatalf(\"invalid offset or corrupt segment: %v\", err)\n    }\n}","preventionTips":["Only use offsets printed by the summary of the same backup file","Re-derive offsets whenever the backup file changes","Compare checksums to detect truncated downloads"],"tags":["backup-restore","protobuf","offset"],"backgroundTag":"protobuf-unmarshal-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"}