juicedata/juicefs · error

failed to read segment: %w

Error message

failed to read segment: %w

What it means

`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>`.

Source

Thrown at cmd/load.go:326

	for _, v := range data {
		fmt.Printf("%-10s| %-10s|", v[0], v[1])
		if withOffset {
			fmt.Printf(" %-10s", v[2])
		}
		fmt.Println()
	}
	return nil
}

func showBakDetail(ctx *cli.Context, fp *os.File, offset int64) error {
	bak := &meta.BakFormat{}
	if _, err := fp.Seek(offset, io.SeekStart); err != nil {
		return err
	}

	seg, err := bak.ReadSegment(fp)
	if err != nil {
		return fmt.Errorf("failed to read segment: %w", err)
	}

	fmt.Printf("Segment: %s\n", seg.Name())
	fmt.Printf("Value: %s\n", seg)
	return nil
}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Use the exact offsets printed by the backup summary (`showBakSummary` lists segment names with offsets) from the same file
2. Verify offset is within the data region, not in the footer or past EOF
3. Re-download/re-create the backup if bytes are missing (compare checksums/size)
4. Upgrade the client if the backup was written by a newer JuiceFS version

Example fix

// before
juicefs load --stat --offset 999999 meta.sqlite3 backup.json   # guess
// after
juicefs load --stat meta.sqlite3 backup.json   # read listed offsets first, then use one exactly

fi, _ := fp.Stat()
if offset <= 0 || offset >= fi.Size() {
    return fmt.Errorf("offset %d out of data range (size %d)", offset, fi.Size())
}

if err := showDetail(fp, offset); err != nil {
    if strings.Contains(err.Error(), "failed to read segment") {
        log.Fatalf("invalid offset or corrupt segment: %v", err)
    }
}

When it happens

Trigger: `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.

Common situations: 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.

Understand the failure class

Background: "cannot parse invalid wire-format data", "cannot unmarshal", "failed unmarshalling": protobuf unmarshal errors explained — this error's family across 10 libraries.

Related errors

• failed to read footer: %w
• The entry of the root inode was not found
• not implemented, use kvMeta.LoadMetaV2 instead
• parse private key: %s
• failed to create plain backup %s: %w

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/122c7be38a19828b. Report an issue: GitHub.