juicedata/juicefs · error

failed to create message by type %d: %w

Error message

failed to create message by type %d: %w

What it means

During backup file loading, Unmarshal reads a protobuf segment whose type byte must map to a known protobuf message via getMessageFromType. This error wraps the failure to instantiate that message, typically because the segment type is unknown/unsupported in this client version or the backup stream is corrupt. It indicates the backup cannot be parsed by this binary.

Source

Thrown at pkg/meta/backup.go:369

		return fmt.Errorf("failed to read segment type: %v", err)
	}

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

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Upgrade the JuiceFS client to a version that supports the segment type in the backup file
2. Verify the backup file integrity (re-transfer, check checksums/size) and re-dump from the metadata engine if corrupt
3. Regenerate the backup with the current client version and retry load

Example fix

// before: older client fails to load backup
juicefs load sqlite3://old.db backup.dump
// after: upgrade client first
juicefs version  # ensure >= version that created the dump
juicefs load sqlite3://old.db backup.dump

if seg.typ > maxKnownSegmentType { return fmt.Errorf("unsupported segment type %d; upgrade client", seg.typ) }

func knownSegmentType(t byte) bool { _, err := getMessageFromType(int(t)); return err == nil }

if err := loadBackup(f); err != nil { if strings.Contains(err.Error(), "failed to create message by type") { /* upgrade client or regenerate dump */ } }

When it happens

Trigger: Loading a dump/backup file whose segment s.typ is not recognized by getMessageFromType; reading a backup produced by a newer JuiceFS version that introduced message types this client does not know; corrupted backup data altering the type byte.

Common situations: Restoring a backup taken with a newer JuiceFS release onto an older client; transferring a truncated or corrupted dump file between environments; mixing versions in disaster-recovery workflows.

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 find message %s's type: %v
• failed to marshal segment %s: %v
• failed to marshal footer: %w
• failed to read footer: err %w, read len %d, expect len %d

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