{"record":{"id":"11cc865912118b53","repo":"juicedata/juicefs","slug":"failed-to-unmarshal-segment-msg-d-w","errorCode":null,"errorMessage":"failed to unmarshal segment msg %d: %w","messagePattern":"failed to unmarshal segment msg (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/meta/backup.go","lineNumber":372,"sourceCode":"\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}\n\nfunc (opt *DumpOption) check() *DumpOption {\n\tif opt == nil {\n\t\topt = &DumpOption{}\n\t}\n\tif opt.Threads < 1 {\n\t\topt.Threads = 10\n\t}","sourceCodeStart":354,"sourceCodeEnd":390,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/backup.go#L354-L390","documentation":"While loading a backup, proto.Unmarshal failed to decode a segment's byte payload into the instantiated protobuf message for that segment type. The type was recognized but the data bytes are not valid protobuf encoding for that message, meaning the segment payload is corrupt or was written with an incompatible schema.","triggerScenarios":"Truncated or bit-rotted backup files; a dump written by a different schema version whose wire format no longer decodes; manual editing/transfer corruption of the dump file.","commonSituations":"Restore from a damaged backup after disk failure; loading a dump copied over an unreliable channel without checksums; schema drift between dump and client versions.","solutions":["Re-create the backup (juicefs dump) from the metadata engine and retry the load","Check for truncation/corruption (compare sizes, checksums) and re-transfer the file","Use a client version matching the one that produced the dump"],"exampleFix":"# before: corrupted dump fails to unmarshal\njuicefs load sqlite3://restore.db backup.dump\n# after: re-dump and verify\njuicefs dump redis://meta redis.dump && shasum redis.dump\njuicefs load sqlite3://restore.db redis.dump","handlingStrategy":"try-catch","validationCode":"if len(data) == 0 || seg.len != uint32(len(data)) { return fmt.Errorf(\"segment %d truncated: got %d want %d\", seg.typ, len(data), seg.len) }","typeGuard":null,"tryCatchPattern":"if err := loadBackup(f); err != nil { if strings.Contains(err.Error(), \"failed to unmarshal segment\") { log.Fatalf(\"backup corrupt at type %s; restore from another copy\", err) } }","preventionTips":["Verify checksums of dump files before loading","Avoid editing dump files manually","Keep dumps on reliable storage with redundancy"],"tags":["protobuf","backup","corruption"],"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"}