juicedata/juicefs · error

unknown message type %d

Error message

unknown message type %d

What it means

When unmarshalling a metadata backup segment, the segment's type byte must map to a known protobuf message name (Format or Batch). If the type byte is out of range or unknown (name resolves to empty), the backup file is corrupt or written by an incompatible version.

Source

Thrown at pkg/meta/backup.go:88

	segTypeXattr:     "xattr",
	segTypeAcl:       "acl",
	segTypeStat:      "stat",
	segTypeQuota:     "quota",
	segTypeParent:    "parent",
	segTypeChangeLog: "changeLog",
}

var errBakEOF = fmt.Errorf("reach backup EOF")

func getMessageFromType(typ int) (proto.Message, error) {
	var name protoreflect.FullName
	if typ == segTypeFormat {
		name = proto.MessageName(&pb.Format{})
	} else if typ < segTypeMax {
		name = proto.MessageName(&pb.Batch{})
	}
	if name == "" {
		return nil, fmt.Errorf("unknown message type %d", typ)
	}
	return createMessageByName(name)
}

func createMessageByName(name protoreflect.FullName) (proto.Message, error) {
	typ, err := protoregistry.GlobalTypes.FindMessageByName(name)
	if err != nil {
		return nil, fmt.Errorf("failed to find message %s's type: %v", name, err)
	}
	return typ.New().Interface(), nil
}

// BakFormat: BakSegment... + BakEOS + BakFooter
type BakFormat struct {
	Pos    uint64
	Footer *BakFooter
}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Regenerate the backup with a matching (same or newer) JuiceFS version
2. Verify the backup file integrity (checksum, size) and re-transfer in binary mode
3. Inspect the first bytes of the file to confirm it is a JuiceFS metadata backup and not another format

// before loading, check the file looks like a JuiceFS backup
info, err := os.Stat(bakFile)
if err != nil || info.Size() < 16 {
    return fmt.Errorf("%s is not a valid JuiceFS backup", bakFile)
}

seg, err := f.Unmarshal(r)
if err != nil {
    if strings.Contains(err.Error(), "unknown message type") {
        return fmt.Errorf("backup file incompatible or corrupt: %w", err)
    }
    return err
}

When it happens

Trigger: Reading a backup/dump file whose segment header contains a type value that is neither segTypeFormat nor < segTypeMax — e.g. a truncated, corrupted, or newer-format backup file passed to Unmarshal.

Common situations: Restoring a backup produced by a newer JuiceFS version into an older client; a backup file damaged in transfer (FTP ASCII mode, truncated copy); pointing juicefs load at the wrong file.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• failed to find message %s's type: %v
• failed to unmarshal segment msg %d: %w
• The entry of the root inode was not found
• failed to get startTS, which is required for TiKV to ensure
• failed to read footer: %w

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