juicedata/juicefs · error

failed to unmarshal segment msg %d: %w

Error message

failed to unmarshal segment msg %d: %w

What it means

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.

Source

Thrown at pkg/meta/backup.go:372

	if s.typ == BakEOS {
		return errBakEOF
	}

	if err := binary.Read(r, binary.BigEndian, &s.len); err != nil {
		return fmt.Errorf("failed to read segment %s length: %v", s, err)
	}
	data := make([]byte, s.len)
	n, err := r.Read(data)
	if err != nil && n != int(s.len) {
		return fmt.Errorf("failed to read segment value: err %v, read len %d, expect len %d", err, n, s.len)
	}

	msg, err := getMessageFromType(int(s.typ))
	if err != nil {
		return fmt.Errorf("failed to create message by type %d: %w", s.typ, err)
	}
	if err = proto.Unmarshal(data, msg); err != nil {
		return fmt.Errorf("failed to unmarshal segment msg %d: %w", s.typ, err)
	}
	s.val = msg
	return nil
}

type DumpOption struct {
	KeepSecret bool
	Threads    int
	Progress   func(name string, cnt int)
}

func (opt *DumpOption) check() *DumpOption {
	if opt == nil {
		opt = &DumpOption{}
	}
	if opt.Threads < 1 {
		opt.Threads = 10
	}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Re-create the backup (juicefs dump) from the metadata engine and retry the load
2. Check for truncation/corruption (compare sizes, checksums) and re-transfer the file
3. Use a client version matching the one that produced the dump

Example fix

# before: corrupted dump fails to unmarshal
juicefs load sqlite3://restore.db backup.dump
# after: re-dump and verify
juicefs dump redis://meta redis.dump && shasum redis.dump
juicefs load sqlite3://restore.db redis.dump

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) }

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) } }

When it happens

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

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

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

• unknown message type %d
• failed to read footer: %w
• failed to find message %s's type: %v
• failed to marshal segment %s: %v
• failed to marshal footer: %w

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