juicedata/juicefs · error

invalid stage footer magic %#04x

Error message

invalid stage footer magic %#04x

What it means

Returned by stageFooter.unmarshal when the staged-file footer magic number does not match stageFooterMagic. The file is not a valid staged cache file (corruption or foreign content), so its tier information cannot be recovered.

Source

Thrown at pkg/chunk/disk_cache_file.go:91

	buff := make([]byte, 0, 4+len(data))
	buff = binary.BigEndian.AppendUint16(buff, stageFooterMagic)
	buff = binary.BigEndian.AppendUint16(buff, uint16(len(data)))
	buff = append(buff, data...)
	return buff, nil
}

func (f *stageFooter) unmarshal(cf *cacheFile) error {
	if cf.footerOff == 0 {
		f.Tier = 0 // no footer, fall back to the default
		return nil
	}
	var hdr [4]byte
	if _, err := cf.File.ReadAt(hdr[:], cf.footerOff); err != nil {
		return fmt.Errorf("read stage footer header: %w", err)
	}
	if magic := binary.BigEndian.Uint16(hdr[:2]); magic != stageFooterMagic {
		return fmt.Errorf("invalid stage footer magic %#04x", magic)
	}
	size := int64(binary.BigEndian.Uint16(hdr[2:4]))
	if size == 0 {
		return fmt.Errorf("invalid stage footer length %d", size)
	}
	if cf.footerOff+4+size != cf.size {
		return fmt.Errorf("stage footer size mismatch: offset %d, size %d, file size %d", cf.footerOff, size, cf.size)
	}
	buf := make([]byte, size)
	if _, err := cf.File.ReadAt(buf, cf.footerOff+4); err != nil {
		return fmt.Errorf("read stage footer data: %w", err)
	}
	if err := msgpack.Unmarshal(buf, f); err != nil {
		return err
	}
	if f.Tier > maxTierID {
		f.Tier = 0 // ignore unknown/corrupted tier, fall back to the default
	}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Delete the corrupted staged file; it will be re-created on next staging
2. Investigate cache disk reliability if it recurs

When it happens

Trigger: Thrown at pkg/chunk/disk_cache_file.go:91 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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