juicedata/juicefs · error

invalid magic number %d, expect %d

Error message

invalid magic number %d, expect %d

What it means

ReadFooter validates the backup file's magic number stored in the footer. If the footer's Magic field does not equal BakMagic, the file is not a JuiceFS metadata backup (or is from an incompatible/older format) and reading is refused.

Source

Thrown at pkg/meta/backup.go:170

		return err
	}
	return f.Footer.Marshal(w)
}

func (f *BakFormat) writeEOS(w io.Writer) error {
	if n, err := w.Write(binary.BigEndian.AppendUint32(nil, BakEOS)); err != nil && n != 4 {
		return fmt.Errorf("failed to write EOS: err %w, write len %d, expect len 4", err, n)
	}
	return nil
}

func (f *BakFormat) ReadFooter(r io.ReadSeeker) (*BakFooter, error) { // nolint:unused
	footer := &BakFooter{}
	if err := footer.Unmarshal(r); err != nil {
		return nil, err
	}
	if footer.Msg.Magic != BakMagic {
		return nil, fmt.Errorf("invalid magic number %d, expect %d", footer.Msg.Magic, BakMagic)
	}
	f.Footer = footer
	return footer, nil
}

type BakFooter struct {
	Msg *pb.Footer
	Len uint64
}

func (h *BakFooter) Marshal(w io.Writer) error {
	data, err := proto.Marshal(h.Msg)
	if err != nil {
		return fmt.Errorf("failed to marshal footer: %w", err)
	}

	if n, err := w.Write(data); err != nil && n != len(data) {
		return fmt.Errorf("failed to write footer data: err %w, write len %d, expect len %d", err, n, len(data))

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Confirm the file is a JuiceFS metadata backup produced by juicefs dump (check with `file`/hexdump of the tail)
2. Regenerate the backup from the metadata engine
3. Use a JuiceFS version compatible with the backup format version

// check file looks like a JFS backup before parsing
fi, err := os.Stat(path)
if err != nil || fi.Size() < 32 {
    return fmt.Errorf("%s is too small to be a JuiceFS backup", path)
}

footer, err := f.ReadFooter(rs)
if err != nil {
    if strings.Contains(err.Error(), "invalid magic number") {
        return fmt.Errorf("not a JuiceFS metadata backup: %w", err)
    }
    return err
}

When it happens

Trigger: Calling ReadFooter (e.g. via showBakSummary) on a file that is empty, truncated to fewer bytes than the footer, or simply not a JuiceFS backup — the tail bytes read as garbage produce a wrong magic value.

Common situations: Running juicefs dump --info / summary against the wrong file; a backup that was truncated or corrupted during transfer; a backup produced by an older format version with a different magic.

Related errors

• update format
• update format
• wrong ranger config: %s
• illegal value for parameter 'ranger-service': " + serviceNam
• No sources given

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