juicedata/juicefs · error

stage footer size mismatch: offset

Error message

stage footer size mismatch: offset %d, size %d, file size %d

What it means

Returned by stageFooter.unmarshal when the footer offset plus header plus declared size does not equal the actual file size — the staged cache file layout is inconsistent, indicating truncation or partial writes.

Solutions

1. Discard the inconsistent staged file so staging is retried
2. Check for processes truncating files in the cache dir

When it happens

Trigger: Thrown at pkg/chunk/disk_cache_file.go:98 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/a9c3d500d0a0002d. Report an issue: GitHub.

Appendix: source

Thrown at pkg/chunk/disk_cache_file.go:98

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
	}
	return nil
}

var (
	stageFooterBaseLen int
	stageFooterPad     [4][]byte
	stageFooterMagic   = uint16(0x4653)

View on GitHub (pinned to c9a67b23e8)